Skip to main content
Glama

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/)

Command

What it does

/orchestrate

Reads a task config, deploys workers in parallel worktrees, monitors/unblocks them, cross-reviews with a rework loop, merges, and cleans up

/plan-worktrees

Interviews you about a feature, decomposes it into parallelizable tasks, and writes the config that /orchestrate consumes

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: hyperpanes-mcp

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:

Round

Tasks

Files

Result

1

weather-model, about-screen, pull-to-refresh

models, UI, routes

3 merged

2

extended-conditions, sunrise-sunset, share-weather

widgets, forecast tiles

3 merged (1 rework)

3

dark-mode, settings, temp-chart, favorite-cities

theme, settings, chart, favorites

4 merged (1 rework)

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

Available Tools

20 tools
herdr_agent_getA

Get agent info by target (pane id, session id or path). Returns agent_status (idle/working/blocked/done/unknown), terminal_title, interactive_ready. Note: agent_status is nested under .agent.agent_status.

Inputs: target (required).

herdr_agent_promptA

Send a prompt to an agent running in a pane. Optionally block until the agent reaches one of these statuses: idle, working, blocked, done, unknown.

Inputs: text (required), target (required), wait.

herdr_agent_readA

Read recent output from an agent's terminal. Used to check for TASK_COMPLETE, blocked questions, or any agent output. For warm-up: read ~400 lines from 'recent' looking for PONG.

Inputs: source (required), target (required), lines, format, +1 more.

herdr_agent_send_keysA

Send key presses to an agent's terminal. Useful for recovery (CtrlC to interrupt a stuck agent) or TUI navigation.

Inputs: keys (required), target (required).

herdr_agent_startA

Launch an opencode agent in a pane. Returns agent info. May need retries if the pane is not ready yet ('not an available shell').

Inputs: kind (required), name (required), pane_id (required), args, +1 more.

herdr_agent_waitA

Block until the agent reaches one of the given statuses (idle, working, blocked, done, unknown). Alternative to polling agent.get in a loop.

Inputs: target (required), until, timeout_ms.

herdr_pane_getA

Get pane info by id. Returns cwd, terminal_id, agent_status, agent (if running opencode), terminal_title, scroll info.

Inputs: pane_id (required).

herdr_pane_listA

List all panes, optionally filtered to a workspace. Each pane has pane_id, cwd, agent_status, terminal info.

Inputs: workspace_id.

herdr_pane_send_inputA

Send text and/or key presses to a pane in one call. Used for warm-up (PING_REPLY_WITH_PONG) and sending commands. Keys are key names like Enter, CtrlC, Backspace.

Inputs: pane_id (required), keys, text.

herdr_pane_splitA

Split a pane, creating a new pane to the right or below. Returns the new pane's pane_id. Essential for launching reviewers in a clean pane.

Inputs: direction (required), cwd, focus, ratio, +1 more.

herdr_pane_wait_for_outputA

Block until the pane output matches a substring or regex, then return the read. More efficient than polling. Returns the matched output lines.

Inputs: match (required), source (required), pane_id (required), lines, +2 more.

herdr_pingA

Ping the herdr server. Returns the server version and protocol.

Inputs: no named parameters.

herdr_session_snapshotA

Dump the full herdr session: workspaces, tabs, panes, layouts and agents. Useful for debugging the entire state at once.

Inputs: no named parameters.

herdr_tab_getA

Get a single tab by id. Returns label, pane_count, workspace_id, agent_status.

Inputs: tab_id (required).

herdr_tab_listA

List tabs, optionally filtered to a workspace. Each tab has tab_id, label, pane_count, agent_status.

Inputs: workspace_id.

herdr_workspace_getA

Get a single workspace by id. Returns label, tab/pane count, worktree info if linked.

Inputs: workspace_id (required).

herdr_workspace_listA

List all open workspaces in herdr.

Inputs: no named parameters.

herdr_worktree_createA

Create a git worktree and open it as a herdr workspace. Returns workspace_id, root_pane.pane_id (for agent.start), and worktree info. The pane may need retries for agent.start if 'not an available shell'.

Inputs: path (required), branch (required), cwd, base, +2 more.

herdr_worktree_listA

List git worktrees for a repository. Returns branch, path, is_linked_worktree, open_workspace_id for each.

Inputs: cwd, workspace_id.

herdr_worktree_removeA

WARNING: Destructive: deletes the worktree checkout and closes its workspace. Does NOT delete the git branch (use git branch -D separately).

Inputs: workspace_id (required), force.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: workspace list/get, tab list/get, pane list/get/split/send_input/wait_for_output, agent start/prompt/get/wait/read/send_keys, and worktree list/create/remove. Even similar tools like pane_send_input and agent_send_keys are clearly differentiated by target (pane vs. agent). No two tools appear to do the same thing.

    Naming Consistency4/5

    The overwhelming majority follow a consistent [resource]_[action] pattern (e.g., workspace_list, pane_split, agent_start, worktree_remove). Exceptions like herdr_ping (verb only) and herdr_session_snapshot (compound noun) are minor deviations that do not obscure the pattern.

    Tool Count4/5

    20 tools is on the higher end but appropriate for the server's broad scope of session management (workspaces, tabs, panes, agents, worktrees). Each tool serves a distinct operational need; none feel redundant. It is slightly above the typical well-scoped range but justified by the domain complexity.

    Completeness4/5

    The tool surface covers list/get for workspaces, tabs, and panes, pane splitting, input/wait operations, agent lifecycle management (start, prompt, get, wait, read, send_keys), and worktree create/remove. Minor gaps exist, such as no explicit pane close or tab management beyond listing, but these can be worked around (e.g., using send_keys or worktree removal).

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Terminal multiplexer MCP server for orchestrating parallel AI agents. Manages workspaces, panes, surfaces with send_input/read_screen/spawn_agent/stop_agent tools. Supports Claude Code, Codex, Gemini, Cursor CLI agents with lifecycle management, browser automation, and agent status push via Claude --channels.
      10
      30
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for hyperpanes terminal workspace app, enabling AI agents to compose and launch workspace layouts, inspect and drive terminal panes, stream output, and orchestrate agent hierarchies.
      50
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to orchestrate Herdr coding agents by wrapping its Unix-socket JSON-RPC API, providing tools for agent management, layout editing, and terminal interaction.
      ISC