herd-orchestrator

Multi-agent worktree orchestrator — an MCP server, opencode commands, and an installer that together turn any AI coding agent into a reactive orchestration engine for git worktrees.

herd-orchestrator/
├── server.js           # MCP server (20 tools)
├── commands/           # /orchestrate + /plan-worktrees
├── tools/              # one file per MCP tool
├── install.sh          # one-command installer
├── test/               # smoke test + tool tests
└── src/client.js       # JSON-RPC client for herdr

What it includes

MCP server (server.js)

20 hand-crafted tools that expose the Herdr terminal API through the Model Context Protocol. No schema auto-generation — each tool is a file with explicit input schemas and descriptions. The full set is orchestration-relevant (worktree.*, agent.*, pane.*, workspace.*, tab.*).

Commands (commands/)

Both commands ship with the operating knowledge learned from real runs (agent start races, TUI prompt swallowing, nested status fields, blocked handling).

Installer (install.sh)

Registers the MCP server in opencode's config and copies all commands to opencode's command directory — without touching your existing MCP entries or configuration. Idempotent, safe with invalid configs, supports --dry-run.

Related MCP server: cmuxlayer

Requirements

• Node.js 18+ (only for the MCP server)

• git (worktrees are native git — always required)

• opencode (to use the commands; subagents are used in git-native mode)

• Herdr (optional) — used by the MCP server and, when available, by /orchestrate. Without herdr, /orchestrate falls back to a git-native mode that creates worktrees itself and drives opencode subagents, so the pipeline still works herdr-free.

Installation

git clone git@github.com:Twinber/herd-orchestrator.git
cd herd-orchestrator
npm install
./install.sh          # global install (~/.config/opencode)

Options: --project, --dry-run, --no-test.

Restart opencode. The herdr_* MCP tools and /orchestrate + /plan-worktrees commands will be available.

Workflow

The orchestrator turns a feature request into merged code through three layers:

1. Plan (/plan-worktrees)

You describe what you want to build. The command interviews you, identifies parallelizable tasks (non-overlapping files, no dependencies), and writes a config file with all the details:

{
  "repo": { "cwd": "/path/to/repo", "base_branch": "main" },
  "issues": [
    { "id": "task-a", "branch": "tasks/task-a", "title": "...", "prompt": "..." },
    { "id": "task-b", "branch": "tasks/task-b", "title": "...", "prompt": "..." }
  ]
}

2. Orchestrate (/orchestrate)

You point the orchestrator at that config. It drives the pipeline in one of two modes, selected automatically at startup:

• herdr mode — when the herdr_* MCP tools respond. Deploys one opencode agent per worktree through herdr:

  worktree.create  →  agent.start  →  agent.prompt  →  agent.get/read/wait
       │                  │               │                 │
    Create worktree   Launch agent    Send task         Monitor
    + workspace       opencode in     to the worker     (working/blocked/
                         the pane                        idle/done)

• git-native mode — when herdr isn't available. The orchestrator creates the worktrees itself with git worktree add and launches opencode subagents with the task tool (workers and reviewers). The pipeline phases are the same; only the transport differs:

  git worktree add  →  task (worker)  →  task (reviewer)  →  git merge
      creates branch     implements in    reviews the diff     integrates
      + worktree dir     the worktree     (APPROVE / REQUEST)  --no-ff

Worktrees are created from the base branch in both modes — each worker starts from the same commit, so they can modify the same files without interfering.

• Cross-review loop — when a worker finishes, a reviewer in a fresh pane inspects the diff. If it says CHANGES_REQUESTED, the feedback goes back to the same worker for fixes, then a new reviewer re-checks. Loop until APPROVE or max_review_rounds is exhausted.

• Integration — approved tasks are merged to the base branch sequentially. Git handles any conflicts automatically (ort strategy).

• Cleanup — workspaces and worktrees are removed; local branches are deleted.

3. Result

The orchestrator reports per task: status, review verdict, and merge result. All commits land on the base branch, each task in its own merge commit, with the original micro-commits preserved in the history.

Real example

In a production run with the app-clima Flutter project (10 tasks), the pipeline completed in three parallel rounds:

A cross-review loop triggered twice (about-screen: missing tests + label fix; temp-chart: missing LineTouchData). Both were resolved in one rework round.

Tests

npm test              # smoke test (MCP handshake + tools/list + tools/call)
npm run test:tools    # unit tests for the read-only tools

License

MIT