Skip to main content
Glama

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) on PATH, with a running core (hc server status)

  • The Herdr desktop app (herdr-app) only for the herdr_app_* tools

Related MCP server: herdr-mcp

Install

npx herdr-mcp            # from npm, once published

or 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 stdio

Claude Code

claude mcp add herdr -- npx -y herdr-mcp

Claude Desktop, Cursor and others

{
  "mcpServers": {
    "herdr": {
      "command": "npx",
      "args": ["-y", "herdr-mcp"]
    }
  }
}

Environment

Variable

Meaning

HERDR_MCP_HC

The hc binary (default: hc on PATH)

HERDR_MCP_APP

The herdr-app binary (default: herdr-app on PATH)

HC_SESSION

The hc session to reach, as for hc itself

HC_TERMINAL_ID

Set automatically inside a Herdr terminal. Passed as the caller, so terminals you start are your children and herdr_wait with children works.

Tools

Terminals and agents

Tool

What it does

herdr_list

Live terminals here and on every connected machine (all includes finished ones; filter by labels)

herdr_get

One terminal's facts: argv, cwd, state, status, exit code, labels, foreground process

herdr_run

Start a program or agent in a new terminal. argv or line, name, cwd, on (machine), labels, task (the agent's first message), background (default true; false waits and returns the output)

herdr_send

Paste text and press Enter; wait for the turn it starts; force only for a dialog the user asked you to answer

herdr_wait

Wait until a terminal is not working, prints output, or children (any/all) report. Timeouts are check-ins, not failures

herdr_read

The screen plus history as plain text

herdr_keys

Press named keys: enter, esc, down, ctrl+c, ...

herdr_interrupt

Stop the current turn (esc for agents, ctrl+c for programs) and report what happened

herdr_kill, herdr_rm

End a program; remove a finished terminal

herdr_label

Set or remove labels

herdr_put

Write a file beside a live terminal, on its machine, for its program to read

herdr_templates

Ready-made agent roles (~/.config/herdr-core/templates/*.md) to run by name

Commands and files, here or on another machine

Tool

What it does

herdr_exec

Run one command without a terminal and get its exit code and exact output (decoded)

herdr_file_read

Read a text file, with offset and limit

herdr_file_write

Write a whole file atomically, making missing folders

herdr_file_edit

Replace exact text; each old must occur once; all edits or none

Every one of these takes on to target a machine from herdr_machines (hc machine add).

Machines and the core

Tool

What it does

herdr_machines

The machines this core has added and their connection state

herdr_status

Core identity, version, uptime and terminal counts; this server's connection

herdr_rpc

Any other herdr-core method by name (doc.get, doc.set, machine.add, terminal.keep, ...). server.stop and server.restart are refused

The window (herdr-app)

Tool

What it does

herdr_app_ls

Spaces, tabs and terminals with pane IDs

herdr_app_status

Layout, selection, focus, overlays, errors

herdr_app_commands

Every window command with its arguments

herdr_app_do

Run one: space.new, tab.new, pane.split, agent.focus, tab.select, ...

herdr_app_shot

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:

  1. Delegate with herdr_run: background: true, a name, a cwd, and the whole task in task. Prefer a template from herdr_templates. Check first_message.sent in the result.

  2. Keep working, then herdr_wait on the terminal (or children: "all") instead of polling.

  3. herdr_read the result before summarizing it. A blocked status means a person is needed: read the screen and ask the user rather than forcing a send.

  4. herdr_kill then herdr_rm only what you started. Never stop the user's core.

  5. 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 label herdr.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 core

src/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 tools
herdr_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

    A3.5/5.0

    Scored across 25 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to remotely drive a vibeOS desktop, including reading the desktop, managing files, editing OS files, and executing commands in the VM.
      444 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      32
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      41
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT