dh-claude-code-orchestrator

A multi-agent orchestrator for Claude Code. You give it a task, it analyzes, plans, builds an agent team (parallel, sequential, or hybrid), executes with conflict-free file coordination, runs mandatory code review, and commits — all from one slash command.

Quick start

# Install once (any of these work):
npx dh-claude-code-orchestrator install        # one-shot, no global install
npm install -g dh-claude-code-orchestrator  # then: claude-orchestrator install
# or, per project:
npx dh-claude-code-orchestrator install --project

# Then in any Claude Code session:
> /orchestrate add JWT auth to the user service

That's it. Claude analyzes the task, presents a plan for your approval, dispatches agents, surfaces progress, runs code review, and commits.

What it does (one paragraph)

You hit /orchestrate <task>. The driver hands the task to a supervisor sub-agent, which classifies the task (scope / risk / parallelism / novelty), picks an execution pattern (parallel fan-out, sequential pipeline, or hybrid), assembles a team from a pool of specialists (architect, implementer, tester, documenter, researcher, etc.), and produces a plan. You approve the plan. Agents are dispatched — multiple in parallel where the file scopes don't overlap, sequential where they must hand off. Throughout, agents coordinate through a file-based message bus (locks, status, messages, artifacts) under the supervisor's mediation. They can spawn child sub-agents for sub-tasks. Sometimes a temporary "skill" is generated mid-run to enforce a uniform pattern across multiple agents (e.g., a custom RFC, a codemod). Once the work is done, a mandatory code review runs (reviewer agent — never skipped, even on small changes). Verdict drives commit (via git-coordinator) or another execution cycle. Final output: clean commits, a written plan, a written review, and an audit trail in .claude/orchestrator/run-<id>/.

Installation

Requires Node.js 18 or newer. No runtime dependencies — pure stdlib.

Global (recommended)

npm install -g dh-claude-code-orchestrator
claude-orchestrator install
# short alias also works:
cco install

Installs the slash commands, agents, and skills to ~/.claude/. Available in every project.

Per project

npx dh-claude-code-orchestrator install --project

Installs to ./.claude/ only. Useful when a project wants its own customized version that travels with the repo.

One-shot (no install)

npx dh-claude-code-orchestrator install

npx fetches and runs the package on the fly — no global install needed.

Dry-run

claude-orchestrator install --dry-run

Shows every file that would be written, changes nothing.

Custom target

claude-orchestrator install --target /path/to/.claude

Useful for non-standard config layouts.

Force overwrite

claude-orchestrator install --force

Skips the safety backup of pre-existing files. Default behavior is to back up any conflicting file as <file>.bak.<timestamp> before overwriting.

Status

claude-orchestrator status

Reports whether the orchestrator is installed at the global and project locations.

Uninstall

claude-orchestrator uninstall          # global
claude-orchestrator uninstall --project  # current project

Removes only the files the orchestrator owns. Your other Claude Code config and any past run directories are left alone.

CLI reference

claude-orchestrator <command> [flags]
cco <command> [flags]                       # short alias

commands:
  install       install commands, agents, skills
  uninstall     remove orchestrator files
  status        report install state at global + project locations
  version       print version
  help          print help

install flags:
  --global      install to ~/.claude/  (default)
  --project     install to ./.claude/
  --target DIR  install to an explicit directory
  --dry-run     print what would happen, change nothing
  --force       overwrite without creating backups

Commands

| Command | Purpose | |---|---| | /orchestrate [task] | Start a new run. Task is optional; will be requested if missing. | | /orchestrate-status | Show the active run's progress, agents, locks, and recent messages. | | /orchestrate-resume [run-id] | Resume a paused or interrupted run. | | /orchestrate-abort | Safely abort the active run, preserving artifacts. |

How a run flows

1. Task captured
   ↓
2. Supervisor analyzes & classifies (~5–15 tool calls)
   ↓
3. Supervisor writes PLAN.md
   ↓
4. ► HIL: user approves / modifies / aborts ◄
   ↓
5. Supervisor dispatches Stage 1 agents (parallel or sequential per plan)
   ↓
6. Agents work; supervisor mediates locks, messages, escalations
   ↓
7. Stage transitions (handoff artifacts frozen)
   ↓                                     ↑
   ... more stages ...                   │
   ↓                                     │
8. Reviewer runs (MANDATORY)             │
   verdict: changes-requested ──────────┘ (max 3 cycles)
   verdict: approved
   ↓
9. Git coordinator commits
   ↓
10. ► HIL: final user approval ◄
   ↓
11. Done. Artifacts in .claude/orchestrator/run-<id>/

The agent team (specialists you can spawn)

| Agent | Role | |---|---| | supervisor | Master planner & coordinator. Spawned automatically. | | planner | Decomposes a stage into ordered concrete steps. | | architect | Freezes interfaces, types, schemas before implementation. | | researcher | Gathers evidence from code, docs, web. Never modifies code. | | implementer | Writes product code within a scoped file set. | | tester | Writes & runs tests. Reports failures back through messages. | | documenter | Updates docs, README, CHANGELOG, doc-comments. | | skill-designer | Creates a temporary, run-scoped skill when needed. | | reviewer | The mandatory gatekeeper. Cannot be skipped. | | git-coordinator | Stages and commits per project conventions. | | hil-broker | Formats human-in-loop questions and records answers. |

Agents can spawn their own children (e.g., one implementer fans out into two for a large module). Recursive supervision is allowed; the parent becomes the local supervisor for its children.

Execution patterns

The supervisor picks one per run:

Parallel

Multiple agents work simultaneously on disjoint file scopes. Best when the task has cleanly separable concerns. The supervisor enforces non-overlap via a lock file (locks.json).

Sequential

Agents pipeline. Each stage's output is frozen as an artifact and handed to the next stage. Best for refactors and migrations.

Hybrid (most common)

A sequential backbone with parallel fans inside stages. Example:

research → architect → (impl-A ∥ impl-B ∥ test-scaffolder) → tester → (documenter ∥ reviewer-prep) → reviewer → git-coordinator

Communication model

No agent reads another's working files directly. All cross-agent traffic goes through:

• Locks (locks.json) — supervisor-managed; ensures no two agents write the same file
• Messages (messages/) — relayed by supervisor
• Status (status/<agent_id>.md) — each agent's heartbeat; supervisor reads
• Artifacts (artifacts/) — frozen handoff outputs between stages

Inter-agent talk is explicit, recorded, and auditable.

Human-in-loop checkpoints

Always paused at:

• After PLAN.md (you approve before execution)
• After review verdict (you confirm before commit)

Conditionally paused for:

• Authentication / authorization changes
• Schema / public-API / breaking changes
• Adding a third-party dependency
• Deletions > 50 lines or any file
• Irreversible actions (drop tables, force-push)
• High estimated cost
• Mid-run scope expansion

For routine changes, no extra HIL — the orchestrator does not over-pause.

Temporary skills

Some runs feature a repeated micro-pattern that all agents must apply uniformly (e.g., "convert every controller to the new error envelope"). For these, the skill-designer agent creates a temp skill into .claude/orchestrator/run-<id>/skills/<name>/SKILL.md and downstream agents are told to consult it. Temp skills die at end of run unless promoted by you.

Mandatory code review

The reviewer agent runs on every run, even tiny ones. It:

• Runs the project's typecheck, lint, tests, and (if configured) audit
• Reads every changed file
• Evaluates correctness / security / robustness / tests / style / scope discipline / documentation
• Issues one of: approved, approved-with-comments, changes-requested

changes-requested loops back to execution (max 3 cycles before user escalation). Failing automated checks → automatic changes-requested. There is no "approve with the user's permission to skip review."

Directory layout (per run)

.claude/orchestrator/
├── CURRENT_RUN
└── run-20260428-101342/
    ├── task.md
    ├── plan/
    │   ├── CLASSIFICATION.md
    │   ├── PLAN.md
    │   └── <stage>-steps.md
    ├── status/<agent_id>.md
    ├── messages/{to-...,from-...,broadcast-...}.md
    ├── locks/locks.json
    ├── artifacts/
    │   ├── architecture/CONTRACTS.md
    │   ├── tests/RESULTS.md
    │   └── stage-N/...
    ├── skills/<temp-skill>/SKILL.md
    ├── hil/{INDEX.md,QUESTION-N.md,ANSWERS.md}
    └── reviews/REVIEW.md

This is your audit trail. Keep, archive, or grep at will.

What this system will NOT do

• Push to a remote without your explicit approval
• Rewrite shared git history
• Skip code review
• Auto-decide on irreversible actions
• Commit known-failing code
• Bypass the file-lock protocol
• Add Claude attribution to commits unless your project explicitly opts in

Customization

Adjusting agent behavior

Edit any agent file in ~/.claude/agents/<name>.md. Agents are markdown with YAML frontmatter; modifying behavior is just editing the prompt body.

Project-specific overrides

Per-project ./.claude/agents/<name>.md overrides the global one of the same name. Useful for shop-specific commit conventions, lint commands, or review checklists.

Adding a new specialist

Drop a new file in ~/.claude/agents/<your-agent>.md with YAML frontmatter (name, description, tools). The supervisor will see it as available.

Tightening or loosening HIL

Edit ~/.claude/skills/human-in-loop/SKILL.md. The supervisor consults this when planning checkpoints.

Troubleshooting

"Claude Code doesn't see /orchestrate" Restart your session. Slash commands are loaded at startup. Verify ~/.claude/commands/orchestrate.md exists.

"Sub-agents aren't running" Verify ~/.claude/agents/*.md files have YAML frontmatter starting with --- and including name: and description:. A malformed frontmatter makes Claude Code skip the file.

"Two agents are fighting over the same file" The plan's file partition is wrong. Read PLAN.md's file table and fix the overlap. Worst case: re-run with a smaller scope.

"Review keeps rejecting" After 3 cycles, escalate is automatic. Read the review document at .claude/orchestrator/run-<id>/reviews/REVIEW.md and decide whether the issues are real (often they are) or whether to override (rare).

"Run got interrupted (Claude Code crashed / restarted)" Run /orchestrate-resume. Supervisor reads state and figures out where to continue.

"I want to start over without finishing" /orchestrate-abort. Artifacts are preserved. To roll back code: git restore / git reset per the rollback section of PLAN.md.

Architecture docs

• docs/ARCHITECTURE.md — deeper design rationale
• docs/AGENTS.md — what each agent does, in detail
• docs/PATTERNS.md — when to use parallel / sequential / hybrid
• docs/EXAMPLES.md — example runs from real-ish tasks

License

Use it, fork it, modify it. Attribution appreciated but not required.