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 check my Herdr session and tell me if any agent needs input"
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 that exposes a running Herdr session to MCP clients such as Grok Bot, Claude Desktop, or any other app that speaks the protocol.
Herdr is a terminal workspace manager for coding agents. It organizes terminals into workspaces, tabs and panes, recognizes the agent running in each pane, and tracks whether it is idle, working, blocked on a dialog, or done. This server lets a desktop assistant see all of that and act on it: read what Claude Code or Codex is doing in your terminal, hand them a prompt, wait for them to finish, run commands in new panes, and react to lifecycle events as they happen.
How it works
Every control tool is a typed wrapper over the
herdrCLI, so name resolution,--waitsemantics and protocol compatibility stay Herdr's job.A background event tap holds one
events.subscribeconnection open on Herdr's Unix socket. It buffers every event with a monotonic sequence number and subscribes topane.agent_status_changedfor each pane, resubscribing when new panes appear. Clients poll withevents_recentor block withevents_wait.Mutating tools carry MCP annotations (
readOnlyHint,destructiveHint) so clients can gate them with per-tool permissions.
Related MCP server: herdr-mcp
Requirements
Herdr 0.9 or newer, with a server running for the session you want to expose (start it with
herdrorherdr server).Python 3.12 or newer and uv.
Install
git clone https://github.com/frysquint/herdr-mcp.git ~/git/herdr-mcp
cd ~/git/herdr-mcp
uv sync
uv run herdr-mcp --helpuv sync creates .venv/bin/herdr-mcp, an absolute entry point that needs
no shell setup. That is the path to hand to desktop clients, which often run
with a minimal PATH.
Grok Bot
Open Grok Bot settings, go to MCP servers, add a server, and paste:
{
"mcpServers": {
"herdr": {
"command": "/home/USER/git/herdr-mcp/.venv/bin/herdr-mcp",
"args": []
}
}
}Replace USER with your login. Grok Bot accepts one server per paste.
If you prefer to run through uv instead of the venv entry point:
{
"mcpServers": {
"herdr": {
"command": "/absolute/path/to/uv",
"args": ["run", "--project", "/home/USER/git/herdr-mcp", "herdr-mcp"]
}
}
}Other MCP clients
Claude Desktop, Claude Code, Codex and most others take the same
command/args shape. For Claude Code:
claude mcp add herdr -- /home/USER/git/herdr-mcp/.venv/bin/herdr-mcpTo serve over HTTP instead of stdio (for remote clients or several clients sharing one tap):
uv run herdr-mcp --transport streamable-http --host 127.0.0.1 --port 8765The endpoint is http://127.0.0.1:8765/mcp. There is no authentication; keep
it on loopback or put it behind something that authenticates.
Configuration
All configuration is through the environment of the server process.
Variable | Effect |
| Path to the |
| Target a named Herdr session instead of the default one. |
| Low-level override of the socket path (CLI and event tap). |
| Run every command against a saved SSH machine profile ( |
| Log level written to stderr. Default |
Tools
Read-only: herdr_status, session_snapshot, workspace_list,
workspace_get, tab_list, pane_list, pane_get, pane_layout,
pane_process_info, pane_read, pane_wait_output, agent_list,
agent_get, agent_explain, agent_read, agent_wait, worktree_list,
events_status, events_recent, events_wait.
Mutating: workspace_create, workspace_focus, workspace_rename,
tab_create, tab_focus, tab_rename, pane_split, pane_run,
pane_send_text, pane_send_keys, pane_rename, agent_prompt,
agent_send_keys, agent_start, agent_rename, agent_focus,
worktree_create, notification_show.
Destructive: workspace_close, tab_close, pane_close.
Event kinds
Broadcast events from Herdr, in underscore form: workspace_created,
workspace_updated, workspace_metadata_updated, workspace_renamed,
workspace_moved, workspace_reordered, workspace_closed,
workspace_focused, worktree_created, worktree_opened,
worktree_removed, tab_created, tab_closed, tab_focused,
tab_renamed, tab_moved, pane_created, pane_closed, pane_updated,
pane_focused, pane_moved, pane_exited, pane_agent_detected,
layout_updated.
Per-pane subscription events: pane_agent_status_changed with
agent_status one of idle, working, blocked, done, unknown.
Synthetic events from the tap itself: tap_connected, tap_disconnected,
tap_events_lost. If you see tap_events_lost, re-read state with
session_snapshot; Herdr does not replay missed events.
A typical delegation loop
agent_listto find a ready agent (statusidleordone).events_recentwithlimit: 0to learnlatest_seq.agent_promptwithwait: true, or send it withwait: falseand thenevents_waitwithsince_seq,kinds: ["pane_agent_status_changed"],pane_id, andagent_status: ["done", "blocked", "idle"].agent_readto collect the response. If the status wasblocked, show the user the dialog text before answering it withagent_send_keys.
Development
uv run pytest
uv run herdr-mcp --log-level DEBUG # speaks MCP on stdin/stdoutThe unit tests fake the herdr binary and do not need a running server.
License
MIT. See LICENSE.
Available Tools
41 toolsagent_explainBRead-onlyIdempotent
Explain how Herdr detected an agent and why it reports its current state.
Inputs: target (required). Returns: object
agent_focusB
Switch the user's view to an agent's pane and mark its completion as seen.
Inputs: target (required). Returns: object
agent_getARead-onlyIdempotent
Get one agent by unique name or hosting pane id.
Inputs: target (required). Returns: object
agent_listARead-onlyIdempotent
List recognized coding agents: kind, name, pane, cwd, status and terminal title.
Inputs: no named parameters. Returns: object
agent_promptA
Submit a prompt to an agent. With wait=true, block until the agent settles (idle, done or blocked by default, or any state in until). Rejected with agent_blocked if the agent is already waiting at a dialog.
Inputs: text (required), target (required), wait, until, +1 more. Returns: object
agent_readARead-onlyIdempotent
Read an agent's terminal output. Use after agent_prompt to see the response; use source=detection for the raw bottom-of-screen text.
Inputs: target (required), ansi, lines, source. Returns: object
agent_renameA
Give an agent a unique name, or clear it when name is omitted.
Inputs: target (required), name. Returns: object
agent_send_keysB
Send logical key presses to an agent's UI, for example ["esc"], ["ctrl+c"], ["enter"], ["y"].
Inputs: keys (required), target (required). Returns: object
agent_startA
Start a coding agent (kind such as claude, codex, grok, opencode, pi) in an existing idle shell pane and name it. Extra args go to the agent's own CLI.
Inputs: kind (required), name (required), pane_id (required), args, +1 more. Returns: object
agent_waitBRead-onlyIdempotent
Wait until an agent reaches a settled state (idle, done or blocked by default, or any state in until).
Inputs: target (required), until, timeout_ms. Returns: object
events_recentBRead-onlyIdempotent
Buffered Herdr events after since_seq, newest last. Kinds include pane_agent_status_changed, pane_agent_detected, pane_created, pane_closed, pane_exited, tab_created, tab_closed, workspace_created, workspace_closed, layout_updated, tap_connected, tap_disconnected. Returns latest_seq to use as the next cursor.
Inputs: kinds, limit, pane_id, since_seq, +2 more. Returns: object
events_statusARead-onlyIdempotent
State of the live event tap: connection, buffer bounds (oldest_seq, latest_seq), and last known agent status per pane.
Inputs: no named parameters. Returns: object
events_waitARead-onlyIdempotent
Block until a matching event arrives after since_seq, or until timeout_ms. Typical: kinds=["pane_agent_status_changed"], agent_status=["done","blocked"]. Returns timed_out=true with no events when nothing matched.
Inputs: since_seq (required), kinds, limit, pane_id, +3 more. Returns: object
herdr_statusARead-onlyIdempotent
Check that Herdr is reachable and report server version plus event tap state.
Inputs: no named parameters. Returns: object
notification_showC
Show a toast inside the Herdr terminal UI.
Inputs: title (required), body, sound, position. Returns: object
pane_closeADestructive
Close a pane and kill its process. Only close panes you created or the user named.
Inputs: pane_id (required). Returns: object
pane_getBRead-onlyIdempotent
Get one pane by id (for example "w1:p3").
Inputs: pane_id (required). Returns: object
pane_layoutBRead-onlyIdempotent
Geometry of the tab containing a pane: rects and split tree. Use it to pick a split direction.
Inputs: pane_id (required). Returns: object
pane_listARead-onlyIdempotent
List panes with cwd, title, hosted agent and agent status, optionally within one workspace.
Inputs: workspace_id. Returns: object
pane_process_infoBRead-onlyIdempotent
Foreground process and shell information for a pane.
Inputs: pane_id (required). Returns: object
pane_readBRead-onlyIdempotent
Read terminal output from a pane. recent-unwrapped joins soft wraps and suits logs; visible is the rendered viewport.
Inputs: pane_id (required), ansi, lines, source. Returns: object
pane_renameB
Set a pane's label, or clear it when label is omitted.
Inputs: pane_id (required), label. Returns: object
pane_runB
Type a shell command into a pane and press Enter. The pane must be at an interactive shell prompt.
Inputs: command (required), pane_id (required). Returns: object
pane_send_keysC
Send logical key presses to a pane, for example ["ctrl+c"] or ["esc"] or ["enter"].
Inputs: keys (required), pane_id (required). Returns: object
pane_send_textB
Send raw text to a pane without pressing Enter.
Inputs: text (required), pane_id (required). Returns: object
pane_splitA
Split a pane to create a new shell pane beside it. Returns the new pane under result.pane. Split wide panes right and tall panes down.
Inputs: pane_id (required), cwd, focus, ratio, +1 more. Returns: object
pane_wait_outputCRead-onlyIdempotent
Block until pane output contains a literal substring (match) or a Rust regex (regex). Output that already exists matches immediately.
Inputs: pane_id (required), lines, match, regex, +2 more. Returns: object
session_snapshotARead-onlyIdempotent
Full live snapshot: workspaces, tabs, panes, agents, layouts and focus. Large; prefer the list tools for routine checks.
Inputs: no named parameters. Returns: object
tab_closeADestructive
Close a tab and every pane process in it. Only close tabs you created or the user named.
Inputs: tab_id (required). Returns: object
tab_createC
Create a tab with one shell pane. Returns the new tab and root_pane ids.
Inputs: cwd, focus, label, workspace_id. Returns: object
tab_focusB
Switch the user's view to a tab (for example "w1:t2").
Inputs: tab_id (required). Returns: object
tab_listARead-onlyIdempotent
List tabs, optionally within one workspace.
Inputs: workspace_id. Returns: object
tab_renameC
Rename a tab.
Inputs: label (required), tab_id (required). Returns: object
workspace_closeADestructive
Close a workspace and every pane process in it. Only close workspaces you created or the user named.
Inputs: workspace_id (required). Returns: object
workspace_createA
Create a workspace with one tab and one shell pane. Returns the new workspace, tab and root_pane ids.
Inputs: cwd, focus, label. Returns: object
workspace_focusC
Switch the user's view to a workspace.
Inputs: workspace_id (required). Returns: object
workspace_getBRead-onlyIdempotent
Get one workspace by id (for example "w1").
Inputs: workspace_id (required). Returns: object
workspace_listARead-onlyIdempotent
List workspaces with their labels, tab/pane counts and aggregate agent status.
Inputs: no named parameters. Returns: object
workspace_renameC
Rename a workspace.
Inputs: label (required), workspace_id (required). Returns: object
worktree_createC
Create a git worktree and open it as a linked workspace.
Inputs: cwd, base, path, focus, +3 more. Returns: object
worktree_listBRead-onlyIdempotent
List git worktrees known to a workspace or repository.
Inputs: cwd, workspace_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
The set is strongly segmented by resource prefix (workspace_, tab_, pane_, agent_, events_, worktree_), and repeated actions such as list/get/create/close target explicit resources. The closest overlaps are pane_read vs agent_read and pane_send_keys vs agent_send_keys, plus the several input tools, but descriptions make the intended conditions clear.
All names use snake_case with a resource/domain prefix, and nearly all are resource_action forms like workspace_list, pane_read, and agent_prompt. Exceptions such as herdr_status, session_snapshot, and events_status are readable status/snapshot nouns and do not break the overall convention.
41 tools is heavy for any single MCP server; even though the terminal/workspace/agent domain is broad, many fine-grained pane/agent input, read, and wait variants could be consolidated or parameterized. The count exceeds the reasonable 3-15 range and sits in the 'too many' band.
Core lifecycle is covered: workspaces, tabs, and panes can be created, listed, renamed, focused, and closed; agents can be started, prompted, waited on, and read; events and worktrees have support. Gaps remain for pane_focus/resize, agent_stop, tab_get, and worktree_remove, though terminal access and close operations provide workarounds.
Maintenance
Related MCP Connectors
Start and manage Reason cloud coding agents, projects and sessions from any MCP client.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to launch and interact with terminal/TUI programs, providing tools to inspect and control live CLI/TUI sessions.23 npm1Apache 2.0
- FlicenseAqualityDmaintenanceEnables coding agents to control and inspect a running Herdr terminal session, including listing workspaces, tabs, panes, and agents, reading pane output, prompting agents, sending keys and commands, waiting for output or state, and splitting or closing panes.14-
- 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
- AlicenseNot gradedqualityCmaintenanceLets MCP clients such as Claude Code, Cursor, and Claude.ai inspect and drive herdr workspaces, panes, and coding agents over a local socket, running either as a local stdio process or as an OAuth-protected HTTP endpoint published through a Cloudflare Tunnel. It exposes tools to create workspaces and tabs, split panes, start and prompt agents, read their output, and wait for results.MIT