ORC

Declarative, resumable, context-isolated workflow orchestrator for Claude Code.

Why ORC?

Claude Code subagents and swarms share context windows, making long workflows noisy and unpredictable. ORC runs each step as an isolated Claude Code session with:

• Fresh context window per step — no cross-contamination between tasks
• Human checkpoints — approval gates and interactive Q&A between steps
• Resumability — interrupted or failed runs pick up where they left off
• Shareable YAML — workflows are declarative and version-controllable

Install

pnpm install
pnpm build
pnpm link --global

Quick Start

orc run examples/simple.yaml

YAML Workflow Format

name: My Workflow

nodes:
  - id: analyze
    prompt: "Analyze the codebase and list key files."
    mode: plan

  - type: approval
    message: "Analysis complete. Proceed with implementation?"

  - id: implement
    prompt: "Implement the suggested changes."

  - id: review
    prompt: prompts/review.md
    interactive: true

Node Types

Prompt nodes run a Claude Code session:

| Field | Required | Description | |---------------|----------|------------------------------------------| | id | yes | Unique identifier (alphanumeric, -, _) | | prompt | yes | Inline text or path to a .md file | | mode | no | plan or default (default: default) | | interactive | no | Enable multi-turn user Q&A (default: false) |

Approval nodes pause for user confirmation:

| Field | Required | Description | |-----------|----------|----------------------| | type | yes | Must be "approval" | | message | yes | Message to display |

Asking the User Questions

Claude has a built-in AskUserQuestion tool — no MCP server or extra configuration needed. When a prompt asks Claude to gather user input, it will invoke AskUserQuestion on its own. ORC intercepts the tool call via the SDK's canUseTool callback, presents the questions in the terminal with arrow-key selection (for options) or free-text input, and returns the answers back to Claude.

- id: gather-info
  prompt: >
    Ask the user what language they prefer using the AskUserQuestion tool.
    Provide options: "TypeScript", "Python", "Go".

Interactive Nodes

When interactive: true, ORC uses session resumption for multi-turn chat:

1. Run the prompt → show formatted output
2. Prompt user for input
3. If user types a response → resume the session with their input → show output → repeat
4. If user presses Enter with no input → node complete

This enables conversational workflows (requirements gathering, iterative planning) without fighting the SDK's process model.

Context Passing

Each node's output is automatically injected into the next node as <previous_node_output> context. This lets multi-step workflows build on prior results without manual wiring.

CLI Commands

orc run <workflow.yaml>    # Execute a workflow
orc resume <run-id>        # Resume an interrupted/failed run
orc runs                   # List all runs
orc inspect <run-id>       # Show run details and node status

Examples

| File | Description | |-----------------------------|----------------------------------------------| | examples/hello.yaml | Multi-step with file prompts and approval gate | | examples/simple.yaml | Two-step analyze + suggest | | examples/interactive.yaml | Interactive feature planning with Q&A |