herdr-mcp
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 start a claude agent in ~/api to fix the failing tests and wait for it"
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.
herdr-mcp
An MCP server for Herdr, the terminal multiplexer for coding agents. It lets any MCP client (Claude Code, Claude Desktop, Codex, Cursor, pi, ...) start and steer agents and programs in terminals that stay alive, run commands and edit files on other machines Herdr knows, and arrange the Herdr window.
Terminals, files and machines go through herdr-core's JSON-RPC API over hc connect, which this
server keeps open for its whole life. Window commands go through the herdr-app CLI.
Requirements
Node.js 20 or newer
herdr-core (
hc) onPATH, with a running core (hc server status)The Herdr desktop app (
herdr-app) only for theherdr_app_*tools
Related MCP server: herdr-mcp
Install
npx herdr-mcp # from npm, once publishedor from source:
git clone https://github.com/kevmo314/herdr-mcp
cd herdr-mcp
npm install && npm run build
node dist/index.js # speaks MCP over stdioClaude Code
claude mcp add herdr -- npx -y herdr-mcpClaude Desktop, Cursor and others
{
"mcpServers": {
"herdr": {
"command": "npx",
"args": ["-y", "herdr-mcp"]
}
}
}Environment
Variable | Meaning |
| The |
| The |
| The hc session to reach, as for |
| Set automatically inside a Herdr terminal. Passed as the caller, so terminals you start are your children and |
Tools
Terminals and agents
Tool | What it does |
| Live terminals here and on every connected machine ( |
| One terminal's facts: argv, cwd, state, status, exit code, labels, foreground process |
| Start a program or agent in a new terminal. |
| Paste text and press Enter; |
| Wait until a terminal is not working, prints |
| The screen plus history as plain text |
| Press named keys: |
| Stop the current turn (esc for agents, ctrl+c for programs) and report what happened |
| End a program; remove a finished terminal |
| Set or remove labels |
| Write a file beside a live terminal, on its machine, for its program to read |
| Ready-made agent roles ( |
Commands and files, here or on another machine
Tool | What it does |
| Run one command without a terminal and get its exit code and exact output (decoded) |
| Read a text file, with |
| Write a whole file atomically, making missing folders |
| Replace exact text; each |
Every one of these takes on to target a machine from herdr_machines (hc machine add).
Machines and the core
Tool | What it does |
| The machines this core has added and their connection state |
| Core identity, version, uptime and terminal counts; this server's connection |
| Any other herdr-core method by name ( |
The window (herdr-app)
Tool | What it does |
| Spaces, tabs and terminals with pane IDs |
| Layout, selection, focus, overlays, errors |
| Every window command with its arguments |
| Run one: |
| Save the window's last frame as a PNG |
How an agent is meant to use it
The server's instructions (sent to the client on connect) follow hc --skill:
Delegate with
herdr_run:background: true, aname, acwd, and the whole task intask. Prefer a template fromherdr_templates. Checkfirst_message.sentin the result.Keep working, then
herdr_waiton the terminal (orchildren: "all") instead of polling.herdr_readthe result before summarizing it. Ablockedstatus means a person is needed: read the screen and ask the user rather than forcing a send.herdr_killthenherdr_rmonly what you started. Never stop the user's core.Use
herdr_app_*only to change what the person sees; new spaces and tabs appear immediately, so create them only when asked. A terminal started with the labelherdr.space=<id>shows up in that space.
Development
npm install
npm run dev # tsx src/index.ts
npm test # build, then a stdio smoke test against the local coresrc/hc.ts is the hc connect JSON-RPC client, src/app.ts wraps the herdr-app CLI, and
src/index.ts defines the tools. hc schema prints the full OpenRPC document the core tools
are built from.
License
MIT
Available Tools
25 toolsherdr_app_commandsWindow: list commandsA
Every window command herdr_app_do can run, with its arguments and what it does.
Inputs: no named parameters.
herdr_app_doWindow: run a commandA
Run a window command: space.new {name, folder, machine, argv, task}, tab.new {name, space, folder, argv, task}, pane.split {direction, pane}, agent.focus {terminal}, tab.select {id}, space.rename {id, name}, ... (herdr_app_commands lists them all). Returns the created IDs. Supply every required argument: commands from an agent never open a dialog. New spaces and tabs are shown immediately: only create them when the user asks, and give them explicit names.
Inputs: command (required), args.
herdr_app_lsWindow: list spacesA
Spaces, their tabs and terminals (with pane IDs) in the open Herdr window. Inspect before acting; use these IDs rather than guessing.
Inputs: no named parameters.
herdr_app_shotWindow: screenshotA
Save the window's last rendered frame as a PNG (its own rendering, even when covered) and return its absolute path. Needs a running window.
Inputs: file.
herdr_app_statusWindow: statusB
What the window shows: layout, selected space and tab, focused pane, overlays, zoom, and any file or mod errors.
Inputs: no named parameters.
herdr_execExec a commandA
Run one command here or on another machine without a terminal and return its exit code and exactly what it wrote. For short commands (git diff, ls, cat). Everything it started ends with it at exit or timeout. Use herdr_run for anything long or interactive.
Inputs: on, cwd, env, argv, +3 more.
herdr_file_editEdit a fileA
Replace exact text in a file here or on another machine. Each old must occur exactly once; edits must not overlap; all are made or none. On edit_failed, add context to make old unique.
Inputs: path (required), edits (required), on, cwd.
herdr_file_readRead a fileA
Read a text file here or on another machine: lines from offset, at most limit. Returns the text and how many lines the file has.
Inputs: path (required), on, cwd, limit, +1 more.
herdr_file_writeWrite a fileA
Write a whole file here or on another machine, making missing folders. Atomic: a reader sees old or new, never half.
Inputs: path (required), text (required), on, cwd.
herdr_getGet a terminalB
One terminal's facts, live or finished: argv, cwd, state, status, exit code, labels, foreground process.
Inputs: terminal (required).
herdr_interruptInterruptA
Press the stop key (esc for agents, ctrl+c for programs) and report what happened. Stops the current turn, not the process.
Inputs: terminal (required), timeout.
herdr_keysPress keysB
Press named keys in a terminal: enter, esc, tab, up, down, ctrl+c, alt+x, f5, a, ... (e.g. to answer a dialog with down, enter).
Inputs: keys (required), terminal (required).
herdr_killKill a terminal's programA
End the program: hangup, then terminate, then kill. Only clean up terminals you started.
Inputs: terminal (required).
herdr_labelLabel a terminalB
Set or remove labels (free-form key=value). An empty string removes a label.
Inputs: labels (required), terminal (required).
herdr_listList terminalsA
Live terminals on this machine and every connected machine, with their status, cwd, labels and parent. Includes the user's other work, not just yours.
Inputs: all, labels.
herdr_machinesList machinesA
The other machines this core has added (over ssh or a command), with their connection state. Use their names in on and machine/t7.
Inputs: no named parameters.
herdr_putPut a file beside a terminalA
Write a file beside a live terminal, on its machine, for its program to read (an image to paste, a patch). Returns where it landed.
Inputs: name (required), terminal (required), text, base64.
herdr_readRead a terminalB
The terminal's screen plus lines of history, as plain text, live or finished.
Inputs: terminal (required), lines.
herdr_rmRemove a finished terminalC
Remove a finished terminal from the list.
Inputs: terminal (required).
herdr_rpcRaw herdr-core callA
Call any herdr-core JSON-RPC method directly (rpc.discover lists them all with their schemas). For methods without a dedicated tool: doc.get, doc.set, machine.add, machine.connect, machine.rename, machine.rm, terminal.keep. server.stop and server.restart are refused: they affect every terminal the user has.
Inputs: method (required), params.
herdr_runRun a program or agentA
Start a program in a new terminal that stays alive. argv runs as given; line runs in the shell; neither opens that machine's shell. If argv[0] names a template (see herdr_templates), its command starts and its body plus task are sent as the first message once the agent is ready. For a plain agent, task is typed as its first message once it is ready. Agents: always background=true, a name, and the whole task up front. Programs: background=false waits for exit (up to timeout) and returns its output in output and how it ended in wait. Returns the terminal (address is what you use afterwards) and, with a task, first_message.sent.
Inputs: on, rm, cwd, env, +9 more.
herdr_sendSend a messageA
Paste text into a terminal and press Enter (once nobody has typed for ~3 s). Refuses a blocked program unless force. With wait=true, also waits for the turn it starts and returns how it ended. Do not resend after an unclear result: read first.
Inputs: text (required), terminal (required), if, wait, +2 more.
herdr_statusCore statusB
herdr-core's identity, version, pid, uptime and terminal counts, plus this server's connection details.
Inputs: no named parameters.
herdr_templatesList templatesA
Ready-made agent roles (reviewer, implementer, ...) by name and description. Run one with herdr_run argv=[name] and a task.
Inputs: no named parameters.
herdr_waitWait on a terminalA
Wait until a program is not working (an agent reports idle/done/blocked/error, or a program exits), or with output, until it prints that text. Use it instead of sleeping or polling. A timeout is a check-in (ended=false), not a failure: wait again. children=all waits until none of the caller's children is working; children=any returns on the next child's news.
Inputs: output, timeout, children, terminal.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Tools are well-differentiated: exec vs run (short vs long/interactive), read (screen) vs get (facts) vs file_read, and send (text) vs keys (named keys) have clear boundaries. The only mild overlaps are put vs file_write (file beside terminal vs atomic whole-file write) and app_do vs rpc, but descriptions draw the line.
Consistent herdr_ prefix with predictable verb_noun (herdr_file_read, herdr_app_do, herdr_kill). A few are nouns (herdr_templates, herdr_machines) for list-like resources, but the herdr_app_* family is grouped cleanly and no style mixing (camelCase) appears.
25 tools is at the heavy edge and spans several sub-domains (terminal control, file ops, app/window, machines, templates). Each earns its place, but some could consolidate (exec/run, app_ls/app_status), landing it borderline rather than well-scoped.
Strong lifecycle coverage: run/send/keys/interrupt/kill/rm/wait/read for terminals, full read/write/edit for files, plus window and machine introspection. A few operations (machine add/connect) are only reachable via herdr_rpc, but that escape hatch plus rpc.discover prevents dead ends.
Maintenance
Related MCP Connectors
Run and manage H Company's Computer-Use Agents from any MCP client.
Remote MCP server for Tandem docs, install guides, SDKs, workflows, and agent setup help.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to remotely drive a vibeOS desktop, including reading the desktop, managing files, editing OS files, and executing commands in the VM.444 npmMIT
- AlicenseBqualityBmaintenanceEnables MCP clients to remotely control a running Herdr session: see agent status, arrange tabs and panes, start and prompt coding agents, and run worktree-isolated jobs over stdio or Streamable HTTP. Includes policy controls such as allowlists, read-only mode, disabled tools, and an audit log.322MIT
- AlicenseBqualityCmaintenanceEnables MCP clients to observe and control a running Herdr session by inspecting panes, agents, layouts, and live lifecycle events, and by prompting agents, waiting for completion, running commands, and managing workspaces, tabs, panes, and worktrees.411MIT
- AlicenseNot gradedqualityBmaintenanceEnables an MCP client to start and drive terminal processes, read and write files, make exact-match text edits, move files, inspect metadata, and paginate through local file-content searches. It also exposes configuration, prompt, usage and recent-call tools alongside those filesystem, search and process capabilities.87 npmMIT