orchestrate

claude-orchestrate

Multi-agent orchestration for Claude Code. Decompose a large goal into a tree of parallel worker / verifier / subplanner sessions running in isolated git worktrees, collect typed handoffs, replan, repeat until terminal.

Adapted from Cursor's /orchestrate skill — same five-primitive contract (Task / Handoff / Workspace / Roles / Loop), reimplemented for Claude Code's substrate: every spawn is a fresh top-level Claude Code session in an isolated worktree, awaited via a claude-bg-wait wrapper around claude --bg --worktree. Uniform spawn substrate; no Agent-tool subagents; daemon-supervised sessions with stable IDs queryable via claude agents --json.

What it does

You type /orchestrate:orchestrate <goal> in Claude Code. The session becomes a root planner: it decomposes the goal into a plan.json task graph, then enters a reconcile loop. Ready tasks spawn in parallel via Bash(claude-bg-wait <worktree-name> <prompt>) — each call creates an isolated git worktree at <repo>/.claude/worktrees/<name>/ and spawns a backgrounded Claude Code session in it. The session does its work, writes a handoff to .orchestrate/handoffs/<task-id>.md in its own worktree, exits. The wrapper detects idle-stable, returns. The planner reads the handoff file from the worktree path, copies to the central workspace, updates state.json, decides what to do next.

Workers, verifiers, and subplanners all use the same spawn substrate. The role contract for each lives in a spawn-prompt template (skills/orchestrate/references/spawning.md) that the planner renders per task — no separate Claude Code subagent definitions, matching Cursor's prompt-canonical design.

Sibling workers don't talk to each other. Context flows up via handoffs and down via the planner's spawn prompts (the planner pastes upstream handoff bodies verbatim into downstream prompts when dependsOn declares a dependency).

Provided

• /orchestrate:orchestrate <goal> — slash command that bootstraps the planner.
• orchestrate:orchestrate skill — operating manual the planner reads (SKILL.md + references/{planner,handoffs,spawning}.md + schemas).
• bin/claude-bg-wait — PATH-accessible wrapper around claude --bg --worktree. Synchronous: spawns + polls + reads logs + (by default) claude stops the session. Supports --keep-session to leave the session alive for claude attach debugging.
• bin/orchestrate-state-write — PATH-accessible helper for atomic JSON writes (tempfile + rename) to avoid mid-write corruption of state.json / plan.json on long runs.

No agents/ directory. Role contracts (worker, verifier, subplanner) live in spawn-prompt templates inside skills/orchestrate/references/spawning.md.

Install

From local marketplace (development)

Clone the repo, then add to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "claude-orchestrate": {
      "source": {
        "source": "directory",
        "path": "/absolute/path/to/this/repo"
      }
    }
  },
  "enabledPlugins": {
    "orchestrate@claude-orchestrate": true
  }
}

Then run claude plugin marketplace add /absolute/path/to/this/repo and claude plugin install orchestrate@claude-orchestrate. Restart Claude Code. /orchestrate:orchestrate should appear in your slash command list, and which claude-bg-wait should resolve to the plugin's bin/ (Claude Code auto-prepends every installed plugin's bin/ to PATH).

From GitHub (after publishing)

{
  "extraKnownMarketplaces": {
    "claude-orchestrate": {
      "source": {
        "source": "github",
        "repo": "odysseus0/claude-orchestrate"
      }
    }
  },
  "enabledPlugins": {
    "orchestrate@claude-orchestrate": true
  }
}

Architecture (TL;DR)

The five primitives the port realizes (substrate-agnostic, lifted from Cursor's design):