Subagent Health Monitor#

Your subagents are dying silently and you don't know until the bill arrives. This MCP server catches it in real-time.

Built from production data: agent teams burn 13-22% of tokens on idle loops and duplicate spawns. This tool surfaces exactly where.

What it tracks#

• Silent failures: subagent with zero progress for >2 minutes → alert
• Token waste: estimates waste from idle notification loops
• Duplicate detection: same task spawning multiple times → alert
• Fleet health score: 0-100 based on stuck agents + token waste

Tools exposed to Claude#

ToolWhat it doesregister_subagentRegister a subagent for trackingcheck_agent_healthCheck a specific subagent's healthrecord_agent_progressLog progress after each tool callget_fleet_healthFleet-wide health summary

Quick start#

Add to ~/.claude/mcp.json:

json

{
  "mcpServers": {
    "subagent-health": {
      "command": "python3",
      "args": ["path/to/subagent-health.py", "--mcp"]
    }
  }
}

Then in Claude Code: "Check fleet health" or "Is subagent-3 stuck?"

Example output#

text

Fleet Health Report
├── Total agents: 4
├── Active: 3
├── Stuck: 1 (agent-2: no progress for 340s)
├── Total tokens: 142,000
├── Estimated waste: 25,560 tokens (18%)
└── Health score: 68/100

ALERT: agent-2 is stuck. Kill and restart with trimmed context.

Prerequisites#

• Python 3.8+
• Claude Code with MCP support
• No API keys required — state stored locally in ~/.claude/