herdr-mesh

# herdr-mesh An MCP server for orchestrating multi-agent workflows inside [herdr](https://herdr.dev), enabling real-time communication, pane management, and contextual handoffs. > 한국어: [README.ko.md](./README.ko.md) ## Why this exists herdr already has everything needed to orchestrate multiple agents — real panes, persistent sessions, semantic agent state (idle/working/blocked/done), and a CLI + socket API to drive it all. What it lacked was a **standard interface for agents themselves to use it.** So when you run several agents inside herdr (Claude, Codex, …), there was no clean way for them to read each other's context, share a session, or pass messages without a human shuffling between terminals. herdr-mesh closes that gap: it exposes herdr's CLI as **MCP tools**, so any MCP-capable agent — regardless of type — can read other agents' panes, hand off context, coordinate, and spawn new agents **on its own, from plain-language instructions.** The goal is to make herdr's multi-agent workflow programmable by the agents themselves, through one standard, agent-agnostic interface. ## Use cases Concrete situations where herdr-mesh turns tedious terminal-shuffling into a single natural-language instruction. ### 1. Code → review → fix loop You have Claude writing code and Codex reviewing it. Codex finds a bug — normally you'd copy it over to Claude by hand. Instead: > "Have Codex review the changes Claude just made. If it finds problems, send them > to Claude to fix, then ask Codex to re-review. Repeat until it's clean." The orchestrating agent uses `herdr_agent_read` (pull Codex's review) → `herdr_agent_send` (hand the findings to Claude) → `herdr_agent_wait` (let Claude finish) → and loops the review. No copy-paste between panes. ### 2. Parallel fan-out > "Split this refactor: have Claude do the API layer and Codex do the tests, then > collect both results and summarize." Spawns/targets two agents with `herdr_agent_start` / `herdr_agent_send`, waits on each with `herdr_agent_wait`, and merges their output with `herdr_agent_read`. ### 3. Long-running handback > "Tell the build agent to run the full test suite, wait until it prints PASS or > FAIL, and bring me the failing cases." Uses `herdr_pane_run` to kick off the run and `herdr_wait_output` to block on the result — so you're notified the moment it's done instead of babysitting the pane. ### 4. Unblock a stuck agent An agent is sitting at a prompt waiting for confirmation (`blocked`) while you're heads-down in another pane. > "Is any agent blocked waiting on input? If Codex is stuck on a y/n prompt, > approve it so it can continue." `herdr_agent_list` surfaces the `blocked` state; `herdr_agent_send` + `herdr_pane_send_keys` answer the prompt — no context-switch on your part. ### 5. Spec → implement → verify pipeline > "Take the plan in the *architect* agent's pane, give it to Claude to implement, > then have the *tester* agent run the suite against the result." Reads the spec with `herdr_agent_read`, hands it off with `herdr_agent_send`, waits with `herdr_agent_wait`, then triggers verification in a third agent — a three-stage relay driven by one instruction. ### 6. Route a question to the agent that has the context > "The agent working in the payments service already has that code loaded — ask it > why the webhook retries, and bring me its answer." Instead of re-loading context yourself, `herdr_agent_send` poses the question to the agent already sitting in that codebase and `herdr_agent_read` returns its reply. The point: the agent-to-agent handoffs that used to need a human in the middle become one sentence. herdr already exposes its workspace/agent runtime over a CLI + socket API. `herdr-mesh` wraps that CLI as [Model Context Protocol](https://modelcontextprotocol.io) tools, so any MCP client can read other agents' panes, send messages, share sessions, and spawn new agents through a standard interface. It is **agent-agnostic**: tools operate on whatever agents herdr recognizes — `pi`, `omp`, `claude`, `codex`, `opencode`, `hermes`, `qodercli`, and any future integration. Targets accept a terminal id, agent name, reported agent label, or legacy pane id; nothing is tied to a specific agent type. Use `herdr_integration_status` to see what's available. ## How it works ``` MCP client ──stdio(MCP)──> herdr-mesh ──exec "herdr …"──> herdr CLI ──socket──> herdr server ``` Each tool runs the `herdr` CLI as a subprocess and returns its JSON output. No separate protocol implementation — herdr's own version/protocol handling stays authoritative. ## Requirements - Node.js 18+ - [herdr](https://herdr.dev) installed and a server running (`herdr status` shows `running`). Set `HERDR_BIN` if `herdr` is not on `PATH`. ## Install (recommended) Install globally, then let the built-in installer detect your agents and register herdr-mesh with them: ```bash npm i -g https://github.com/runchr-works/herdr-mesh/archive/refs/heads/main.tar.gz herdr-mesh install ``` > Installed straight from GitHub (not the npm registry). The repo ships a prebuilt > `dist/`, so install needs only network access — no build step. To update later, > re-run the same command. > > The shorter `npm i -g runchr-works/herdr-mesh` also works on npm setups that > handle git installs cleanly; if it doesn't create a working `herdr-mesh` command, > use the tarball URL above. Don't want a global install at all? See > [Manual registration](#manual-registration) — `npx` works without one. `herdr-mesh install` detects installed agents and registers herdr-mesh with the ones you pick: - **Claude Code** — via `claude mcp add -s user` - **Codex** — adds `[mcp_servers.herdr-mesh]` to `~/.codex/config.toml` - **opencode** — merges into `~/.config/opencode/opencode.json` - Other agents — prints the exact config snippet to paste It is **safe**: existing config is parsed and merged (never overwritten), a `.bak` backup is made before writing, and re-running skips agents already registered. Use `herdr-mesh install -y` to register with all detected agents non-interactively. Restart the agent(s) afterward so they pick up herdr-mesh. ## Manual registration Each agent is its own MCP client; register herdr-mesh once per agent. All agents on the same machine share the same herdr socket, so they can see and message each other. The server command is `herdr-mesh` (after a global install). Claude Code: ```bash claude mcp add -s user herdr-mesh herdr-mesh ``` Codex (`~/.codex/config.toml`): ```toml [mcp_servers.herdr-mesh] command = "herdr-mesh" ``` Generic MCP config (stdio): ```json { "mcpServers": { "herdr-mesh": { "command": "herdr-mesh" } } } ``` > Prefer not to install globally? Use `npx -y runchr-works/herdr-mesh` as the > command instead of `herdr-mesh` (npx fetches the prebuilt repo from GitHub; > first run is slower while it downloads). ## Build from source (local development) ```bash git clone https://github.com/runchr-works/herdr-mesh.git cd herdr-mesh npm install npm run build node dist/index.js # run the server directly node dist/index.js install # or run the installer from source ``` ## Usage — just talk to your agent You don't type tool names. Talk to your agent (Claude, Codex, …) in plain language; it decides when to call a herdr-mesh tool and reports back. The phrases below are examples of what to say and which capability they trigger. **See what's running** - "What agents are running in herdr right now?" → lists agents + status - "Which agent integrations does herdr support?" → integration status **Read another agent's context (handoff in)** - "Read the codex pane and summarize what it's working on." - "Grab the last 100 lines from the agent named *reviewer*." **Send a message / hand off work** - "Tell codex: 'please review the diff on this branch'." - "Ask the *reviewer* agent to run the tests and report back." - "Send `npm test` to pane w65343…-3 and run it." (executes with Enter) **Coordinate / wait** - "Wait until codex is idle, then send it the next task." - "Watch the build pane and tell me when it prints 'BUILD SUCCESS'." **Spawn / manage agents** - "Start a new codex agent in a split to the right and have it review my work." - "Open a new agent named *tester* running claude." **Sessions & workspace** - "List herdr sessions." / "Create a new workspace for the docs project." A typical handoff, all from natural language: > "Take my current changes, hand them to a fresh codex agent for review, wait > for it to finish, then summarize its feedback for me." The agent chains `herdr_agent_start` → `herdr_agent_send` → `herdr_agent_wait` → `herdr_agent_read` on its own. **Good to know when phrasing requests** - Be explicit about whether you want a message just *delivered* vs *run/submitted* — e.g. "just type it for them" vs "send it and run it". (Delivery only types text into the other agent's input; it does not press Enter.) - If output looks empty, ask for it "based on what's **on screen** now". The "recent command output" region can be empty when nothing has been tracked. ## Tools (reference for the LLM) These are the tool names exposed to the agent — listed here for reference, not for you to type. **Agent messaging & context (core)** - `herdr_relay` — deliver a message to an agent **and submit it** (types + Enter). Preferred for messaging; avoids the "typed but never submitted" pitfall. - `herdr_handoff` — send a task, wait for the agent to finish, and read its result back — in one step. Preferred for review/fix/verify loops so the chain can't break. - `herdr_agent_list` — list agents with state (idle/working/blocked/done) - `herdr_agent_get` — agent details - `herdr_agent_read` — read another agent's pane output (context handoff) - `herdr_agent_send` — low-level: type literal text to an agent (no Enter) - `herdr_agent_wait` — block until an agent reaches a status - `herdr_wait_output` — block until a pane's output matches text/regex **Agent lifecycle & discovery** - `herdr_agent_start` — spawn a new agent terminal (any supported agent) - `herdr_agent_rename`, `herdr_agent_focus` - `herdr_integration_status` — list agent integrations herdr knows about and their status **Sessions** - `herdr_session_list`, `herdr_session_stop`, `herdr_session_delete` **Panes** - `herdr_pane_list` / `get` / `read` / `split` / `run` / `send_text` / `send_keys` / `close` / `rename` - Use `herdr_pane_run` to type a command **and** press Enter; use `*_send_text` for literal text. **Tabs & workspaces** - `herdr_tab_*` — list / create / get / focus / rename / close - `herdr_workspace_*` — list / create / get / focus / rename / close ## Behavior notes (for the LLM / developers) Tool-level behavior details — not end-user tips, but what the LLM relies on to use the tools correctly and what developers should understand. - **Sending messages / commands** - Deliver text only: `herdr_agent_send` (does not press Enter) - Also submit it: follow with `herdr_pane_send_keys` sending `enter` - Run a shell command: `herdr_pane_run` (types **and** presses Enter) — simplest - **Reading output**: for context retrieval, `source: "visible"` most reliably returns on-screen content. `recent` / `recent-unwrapped` can be empty when there is no tracked command-output region. ## Context & session sharing - **Context sharing**: pull another agent's output with `herdr_agent_read`, push to it with `herdr_agent_send` / `herdr_pane_run`. - **Sessions**: all agents attached to the same herdr server already share one session (socket) — that's the foundation context sharing relies on. Over MCP you can observe/manage sessions (`session_list` / `stop` / `delete`). Human remote `session attach` (SSH attach) is a native herdr feature and interactive, so it is intentionally excluded from the MCP tools. ## Troubleshooting Natural-language requests usually work, but the agent (an LLM) ultimately decides whether and how to call the tools, so it isn't 100% deterministic. If something doesn't happen: - **The agent answered without acting.** Be explicit: name the capability, e.g. "use herdr-mesh to message codex" or "call the herdr tools to do this". - **A message was sent but nothing ran.** `herdr_agent_send` types without Enter. Ask to "send it **and run it**", or rely on `herdr_relay` / `herdr_handoff`, which submit for you. - **Wrong or missing target.** Tell it to "list the agents first", then refer to one by the name/id from that list. - **Read came back empty.** Ask for output "from what's **on screen** now" (`source: visible`); tracked "recent" output can be empty. - **A multi-step handoff stalled midway.** Use `herdr_handoff` (send + wait + read in one tool) instead of asking the agent to chain several calls itself. - **Tools not available at all.** Check the server is connected: `claude mcp list` or `/mcp` inside the session. Confirm herdr is up with `herdr status`. - **Still stuck?** Errors are returned verbatim from herdr, so ask the agent to "show the exact error it got" — it usually names the cause (e.g. `agent_not_found`). ## Development ```bash npm run dev # run from source via tsx npm run build # compile to dist/ ``` > `dist/` is committed so the package installs from GitHub without a build step. > After changing anything under `src/`, run `npm run build` and commit `dist/` too. ## License MIT