agent-top
htop for local coding agents.
You have three Claude Code sessions, a Codex thread in VS Code, and a Gemini CLI you forgot about. Which one is burning tokens right now? Which one is waiting on you? Which MCP server is still alive after the agent that started it died? agent-top answers that in one terminal view, the way htop answers it for processes and btop answers it for the whole machine.
Recorded from a synthetic snapshot (docs/demo-snapshot.json, replayed with --replay) rather than a live machine, because a recording of real sessions would publish real project names, working directories and session ids. Regenerate with vhs docs/demo.tape.
What it shows
| Column | Meaning |
|---|---|
| STATE | running = mid-turn (inference or tool execution), idle = alive and waiting for you, stopped = transcript with no live process (kept for 30 minutes) |
| TOKENS | input + cache read + cache write + output, from the harness's own transcript |
| COST | USD at list price. + or ≥ means some tokens had no known price and the number is a floor |
| CPU% / MEM | summed over the agent's whole process tree |
| TOOLS | tool calls in the session |
| PROCS / MCP | processes in the tree, and how many of them look like Model Context Protocol servers |
| AGE | process age, or time since the last transcript write for stopped sessions |
The detail pane shows the process tree (agent, subagent, mcp, shell, tool) and the token breakdown. Orphaned MCP processes, servers with no live agent above them, are listed in red. That is the failure mode reported repeatedly against Codex (openai/codex #17574, #25015, #12491, #16256) and it is not specific to Codex.
Supported harnesses
| Harness | Discovery | Tokens and cost | State |
|---|---|---|---|
| Claude Code | process table + ~/.claude/sessions/<pid>.json (exact) |
transcript usage, priced per model | harness-reported |
| Codex CLI / app-server | process table + rollout cwd match (heuristic) |
transcript usage; unpriced until a price table exists | transcript events |
| Gemini CLI, OpenCode, Aider, Copilot CLI, cursor-agent | process table only | not yet | CPU heuristic |
Install
Or, without Homebrew:
Prebuilt binaries for macOS and Linux (x86_64 and arm64) are attached to every release with checksums. Building from source needs Rust 1.85+ (edition 2024). Either way: one static binary, no Python, no Node, no daemon.
Usage
--replay renders a saved snapshot in the full interactive UI without reading
anything on the local machine, so a bug report can be inspected exactly as the
reporter saw it.
Keys: j/k move, s cycle sort, r reverse, t toggle the detail pane,
Tab switch that pane between the process tree and the tool trace, x hide
stopped sessions, p pause, ? help, q quit.
Tool trace
Tab turns the detail pane into a waterfall of the selected agent's recent
tool calls, on a shared time axis:
tool trace 5 of 71 calls · window 1m00s
in tools 58% slowest Bash 20.0s 1 in flight 1 failed
Bash 2.5s ▉▉▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏
Read 40ms ▏▏▉▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏
↳Grep 12.0s ▏▏▉▉▉▉▉▉▉▉▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏
Edit 300ms! ▏▏▏▏▏▏▏▏▏▏▏▏▉▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏
Bash 20.0s… ▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▉▉▉▉▉▉▉▉▉▉▉▉▸
Width is the call's share of the window; colour is how long it took, on a
log scale from green under a second, through amber, to red approaching a
minute. Those are two channels on purpose: at a typical zoom most calls are one
cell wide, so width alone would say nothing about a 40 ms read next to a 30 s
test run. ↳ and blue mark a subagent's call, … and amber a call still
running, ! and red one the harness reported as failed.
in tools is the share of the window covered by at least one call (overlapping calls merged, not summed) — the rest is the model thinking, which is usually the answer to "why has this agent been busy for eight minutes".
No configuration and no telemetry opt-in: the spans are reconstructed from the
transcript the harness already writes, by pairing each call with its result
(Claude's tool_use / tool_result on tool_use_id, Codex's function_call /
function_call_output on call_id) and reading the timestamps that bracket
them. Only the call's name, id and timing are read, never its arguments or
output. The spans are in --json as well, so they can be fed to a real tracing
tool.
How it works
- Enumerate processes with
sysinfo. Anything whose program isclaude,codex,gemini,opencode,aider,copilotorcursor-agent(or a Node script under the corresponding npm package) is an agent root. Harness processes nested under a root are subagents of that root. - Attribute a transcript to each root. Claude Code writes
~/.claude/sessions/<pid>.jsonwith the session id, cwd, a derived name and a busy/idle status, so attribution is exact. Codex is matched by working directory and start time. - Tail the transcript incrementally (byte offset kept between refreshes) to accumulate usage, tool calls, turns and the last event, which decides
runningvsidle. - Price each message by its model from a static table. Unknown models are counted as unpriced tokens rather than guessed.
- Any MCP-looking process with no agent ancestor is an orphan.
Everything is read-only. agent-top never signals, writes to, or talks to an agent.
Roadmap
See docs/roadmap.md. Short version: exact Codex attribution, a logical subagent tree from transcripts, trace export to OTLP, user-supplied price tables, and a hook subcommand for harnesses that support it. docs/releasing.md is the release runbook.
Development
crates/agent-top-core is discovery and accounting with no terminal dependency; crates/agent-top is the ratatui front end. The internal engineering handbook (PRD, RFCs, ADRs, decisions) lives in the sibling agent-top-internal-docs repository.
License
MIT