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

Related MCP server: all-agents-mcp

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

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

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