cc-agent-monitor

Claude Code subagent monitoring.

English | 한국어

What Is This

Tracks how many subagents spawn per session, what they do, and how many tokens they use.

• Real-time statusline — view directly in the statusline, no separate window needed.
• One-command setup — cc-agent-monitor init registers hooks and config automatically.
• No dependencies — no external packages.

Quick Start

npm install -g cc-agent-monitor
cc-agent-monitor --init

init registers the hooks and creates a config file. That's it. You can also run npx cc-agent-monitor --init.

Use --skip-init to skip the interactive setup and use all defaults.

After init, start Claude Code and the statusline appears automatically each session.

Configuration

cc-agent-monitor config          # Show current config
cc-agent-monitor config --reset  # Reset to defaults

| Setting | Default | Description | |---------|---------|-------------| | liveColor | neon-cycle | LIVE indicator color | | mainColor | orange | Main session color | | staleThresholdMs | 900000 | Stale threshold (15 min) | | rows.value | 5 | Max visible statusline rows |

How It Works

After setup, this table shows up at the bottom of your terminal:

✦ Agents ────────────────────────────────────────────────────
│ Status       │ Agent    │ Task                     │ Used  │
├──────────────┼──────────┼──────────────────────────┼───────┤
│ ◉ LIVE       │ main     │ (general-purpose) impl…  │ ----  │
│ ◉ LIVE       │ main     │ (Explore) find config…   │ ----  │
│ ◉ done(31s)  │ main     │ (Plan) design approach   │ ~12k  │
│ ● LIVE       │ reviewer │ code review task-001     │ ----  │
└──────────────┴──────────┴──────────────────────────┴───────┘

| Column | Meaning | |--------|---------| | Status | ◉ LIVE active built-in / ● LIVE active custom / done(Ns) completed / ⚠ stale no update | | Agent | main = built-in types / custom name for user-defined agents | | Task | (type) description for built-in / description for custom | | Used | Token count. ---- = running (tokens show on completion) |

Three moving parts.

1. Hooks fire on agent lifecycle events. SubagentStart, SubagentStop, PostToolUse, Stop.
2. State files collect per-agent records. ~/.cc-agent-monitor/state/{sessionId}/
3. Statusline reads them and draws the table.

Limitations

• Running agents show ---- for tokens. Numbers appear when all tasks complete. (anthropics/claude-code#43456)
• Compacted sessions — token data tracking may be affected.
• Teammate/swarm — different lifecycle, not tracked.

Requirements

• Node.js 18+
• Claude Code with hook support
• Tested on Windows PowerShell + Claude Code CLI only. macOS/Linux and VS Code extension not yet tested.

License

MIT