herdr-mcp
This MCP server exposes the Herdr terminal multiplexer API, enabling AI agents to orchestrate multi-agent workflows across git worktrees through 20 specialized tools.
Server & Session Management
herdr_ping— Check server connectivity and retrieve version/protocol infoherdr_session_snapshot— Dump the full session state (workspaces, tabs, panes, layouts, agents) for debugging
Workspace Management
herdr_workspace_list— List all open workspacesherdr_workspace_get— Retrieve details of a specific workspace (label, tab/pane count, worktree info)
Tab Management
herdr_tab_list— List tabs, optionally filtered by workspace, with agent status infoherdr_tab_get— Get details of a specific tab
Pane Management
herdr_pane_list— List all panes, optionally filtered by workspaceherdr_pane_get— Get detailed pane info (cwd, agent status, terminal info, scroll info)herdr_pane_split— Split a pane right or down to create a new pane (used for launching reviewers)herdr_pane_send_input— Send text and/or key presses to a paneherdr_pane_wait_for_output— Block until pane output matches a substring or regex pattern
Agent Lifecycle
herdr_agent_start— Launch an opencode agent inside a paneherdr_agent_prompt— Send a prompt to a running agent, optionally waiting for a specific status (idle/working/blocked/done/unknown)herdr_agent_get— Retrieve current agent status and infoherdr_agent_wait— Block until an agent reaches one of the specified statusesherdr_agent_read— Read recent terminal output from an agent (useful for checking task completion or blocked questions)herdr_agent_send_keys— Send key presses to an agent's terminal (e.g., CtrlC to interrupt a stuck agent)
Git Worktree Management
herdr_worktree_create— Create a git worktree and open it as a Herdr workspace, returning workspace and pane IDsherdr_worktree_remove— Destructively remove a worktree checkout and close its workspaceherdr_worktree_list— List all git worktrees for a repository with branch, path, and workspace info
These tools enable building multi-agent orchestration systems where agents work simultaneously in separate worktrees, with cross-review loops and automated merging.
Provides tools for managing git worktrees, including creating, listing, and removing worktrees, enabling parallel development workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@herdr-mcp split the current pane vertically"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 herdrWhat 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 |
| Reads a task config, deploys workers in parallel worktrees, monitors/unblocks them, cross-reviews with a rework loop, merges, and cleans up |
| Interviews you about a feature, decomposes it into parallelizable tasks, and writes the config that |
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,/orchestratefalls 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 addand launches opencode subagents with thetasktool (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 untilAPPROVEormax_review_roundsis 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 toolsLicense
MIT
Available Tools
20 toolsherdr_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
Scored across 20 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Related MCP Servers
- AlicenseAqualityBmaintenanceTerminal 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.1030Apache 2.0
- AlicenseAqualityBmaintenanceMCP 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.501MIT
- FlicenseAqualityDmaintenanceA simple MCP server that exposes a terminal tool, allowing AI agents to execute shell commands.1-
- AlicenseNot gradedqualityDmaintenanceEnables 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