Agent Herder

MCP server for monitoring and controlling coding agents.

One unified MCP interface to monitor and manage sessions across three coding agent harnesses:

• OpenCode — via HTTP server API (opencode serve)
• Claude Code — via CLI and session files
• Codex CLI — via CLI

What it does

Monitoring

• List all agents — which are running, idle, stopped, or need input
• Inspect agent details — model, cost, duration, message count, working directory
• See pending permissions — agents waiting for tool approval

Management

• Send a message — sync (wait for response), queue (fire-and-forget), or steer (redirect)
• Resume a stopped agent — with an optional new message
• Stop an agent — abort a running session
• Respond to permission requests — allow or deny tool calls (OpenCode)
• Set permissions — configure allowed tools and permission modes

Prerequisites

At least one of:

• opencode installed and opencode serve running
• claude (Claude Code CLI) installed
• codex (OpenAI Codex CLI) installed and OPENAI_API_KEY set

Install

npm install
npm run build

Configure

Environment Variables

Variable	Default	Description
ENABLE_OPENCODE	true	Enable OpenCode adapter
ENABLE_CLAUDE	true	Enable Claude Code adapter
ENABLE_CODEX	true	Enable Codex adapter
OPENCODE_URL	http://127.0.0.1:4096	OpenCode server URL
OPENCODE_SERVER_PASSWORD		Password for OpenCode server auth
OPENCODE_SERVER_USERNAME	opencode	Username for OpenCode server auth
CLAUDE_BIN	claude	Path to Claude Code CLI binary
CODEX_BIN	codex	Path to Codex CLI binary
CODEX_DATA_DIR	~/.codex	Codex data directory

Add to your MCP client

Claude Code:

claude mcp add agent-herder -- node /path/to/agent-herder/dist/index.js

Cursor / other MCP clients — add to your MCP config:

{
  "mcpServers": {
    "agent-herder": {
      "command": "node",
      "args": ["/path/to/agent-herder/dist/index.js"],
      "env": {
        "ENABLE_OPENCODE": "true",
        "ENABLE_CLAUDE": "true",
        "ENABLE_CODEX": "false"
      }
    }
  }
}

OpenCode — add to opencode.json:

{
  "mcp": {
    "agent-herder": {
      "command": "node",
      "args": ["/path/to/agent-herder/dist/index.js"]
    }
  }
}

Available Tools

Tool	Description
list_agents	List all sessions, filter by harness or status
agent_info	Get detailed info about a specific session
send_message	Send a message (sync/queue/steer)
resume_agent	Resume a stopped session
stop_agent	Abort a running session
respond_permission	Allow/deny a pending permission request
set_permissions	Set allowed tools and permission mode

Architecture

┌─────────────────┐
│   MCP Client    │  (Claude Code, Cursor, OpenCode, etc.)
└────────┬────────┘
         │ stdio (MCP protocol)
┌────────▼────────┐
│  Agent Herder   │  (this server)
│  ┌───────────┐  │
│  │ MCP Tools │  │  7 unified tools
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼──────┐ │
│  │  Adapters  │ │
│  ├────────────┤ │
│  │ OpenCode   │──┼── HTTP → localhost:4096
│  │ Claude     │──┼── CLI + ~/.claude/sessions
│  │ Codex      │──┼── CLI + ~/.codex/sessions
│  └────────────┘ │
└─────────────────┘

Harness-specific notes

OpenCode

• Best supported — full HTTP API with session management, permissions, SSE events
• Requires opencode serve running (auto-starts with TUI on port 4096)
• Supports remote permission response and real-time status

Claude Code

• Sessions read from ~/.claude/projects/*/sessions/*.jsonl
• Sending messages uses claude -p --resume <id>
• Permissions must be set at launch via --allowedTools flag
• Running process detection via pgrep

Codex CLI

• Sessions read from ~/.codex/sessions/
• Sending messages spawns new codex invocations
• Uses --full-auto mode for unattended operation
• Permissions set at launch via --full-auto, --approve-tools flags

Development

npm run dev        # TypeScript watch mode
npm run build      # Compile
npm run inspect    # Open MCP Inspector for interactive testing

License

MIT