herdr-mcp

MCP server that lets AI assistants orchestrate coding agents running in Herdr by wrapping its Unix-socket JSON-RPC API (~/.config/herdr/herdr.sock, newline-delimited JSON, verified against Herdr 0.7.1 / socket protocol 14).

Requirements

A running Herdr server (the socket must exist; check with herdr agent list)
Node.js ≥ 20
macOS or Linux (the transport is a Unix domain socket)

Build

git clone <this-repo> && cd herdr-mcp
npm ci
npm run build     # emits dist/

The server binary is then node /abs/path/to/herdr-mcp/dist/index.js. All examples below use that form; substitute your absolute path. To run from source instead (no build step), use npx tsx /abs/path/to/herdr-mcp/src/index.ts.

Set the HERDR_SOCKET environment variable if your socket is not at ~/.config/herdr/herdr.sock.

Installation

Claude Code

claude mcp add --scope user herdr -- node /abs/path/to/herdr-mcp/dist/index.js

(--scope user makes it available in every project; omit for project-local.) Verify with /mcp inside a session.

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), then restart the app:

{
  "mcpServers": {
    "herdr": {
      "command": "node",
      "args": ["/abs/path/to/herdr-mcp/dist/index.js"]
    }
  }
}

Cursor

Settings → MCP → Add server, or ~/.cursor/mcp.json (global) / .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "herdr": {
      "command": "node",
      "args": ["/abs/path/to/herdr-mcp/dist/index.js"]
    }
  }
}

VS Code (Copilot agent mode)

.vscode/mcp.json in a workspace, or run MCP: Add Server from the command palette:

{
  "servers": {
    "herdr": {
      "type": "stdio",
      "command": "node",
      "args": ["/abs/path/to/herdr-mcp/dist/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "herdr": {
      "command": "node",
      "args": ["/abs/path/to/herdr-mcp/dist/index.js"]
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.herdr]
command = "node"
args = ["/abs/path/to/herdr-mcp/dist/index.js"]

To pass a non-default socket path in any client, add an env block, e.g. "env": { "HERDR_SOCKET": "/run/user/1000/herdr.sock" }.

Tools

Tool	Kind	What it does
`list_agents`	read	Agents with live status and the `agent_id` used to target them
`get_layout`	read	Full tree: workspaces → tabs → panes with split geometry; every pane marked `agent` (with status) or `shell`
`read_pane`	read	Any pane's screen (`visible` / `recent` / `detection` sources)
`wait_for_agent_status`	read	Blocks until an agent reaches a status (event-driven, per-pane `events.subscribe`); timeout reported, not thrown
`wait_for_output`	read	Blocks until a pane's output matches a substring/regex (`pane.wait_for_output` on a dedicated connection)
`send_to_agent`	acts	Types into an agent's terminal; explicit `submit` flag controls the newline; validates the target first and returns the pane's screen as evidence
`send_keys`	acts	Named keys (`enter`, `c-c`, `escape`, …) to any pane, with screen evidence
`start_agent`	acts	Launches an agent (`agent.start`) in a new pane
`edit_layout`	acts	split / move / swap / resize / zoom / close_pane; refuses to close agent panes; returns resulting layout
`manage_tabs`	acts	create / rename / focus / close for tabs and workspaces; refuses to close containers holding agents
`manage_worktrees`	acts	Herdr's git-worktree integration (list / create / open / remove)
`notify_user`	acts	Desktop notification via `notification.show`
`herdr_rpc`	acts	Raw escape hatch to any socket method (full API parity; `server.stop` refused)

Herdr quirks the client absorbs (0.7.1): the server closes the connection after every reply, so requests are serialized through a queue with one transparent retry; pane.split / pane.resize act on the focused pane (edit_layout focuses the target tab and restores focus after); event subscriptions are per-pane.

Development

npm run dev      # run the server on stdio
npm run inspect  # MCP Inspector against the live server
npm run check    # biome lint + tsc + vitest

Layout: src/protocol.ts (wire types, zod schemas, guards) → src/connection.ts (one NDJSON connection: framing, id correlation, pushes) → src/herdr-client.ts (HerdrApi interface + reconnecting client; one dedicated connection per event subscription) → src/tools.ts (MCP tools against HerdrApi) → src/index.ts (stdio wiring).

Notes for extenders: Herdr 0.7.1 closes the connection after each reply — the client transparently retries once on a fresh connection (never for server-answered errors). Tool output is deliberately shaped (src/views.ts); don't dump raw socket JSON into Claude's context. Tools depend on the HerdrApi interface, so new tools are testable against the in-memory fake in test/tools.test.ts.