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.