A top for coding-agent sessions. If you keep several Claude Code sessions and Codex runs going at once, agents-top shows them all in one terminal view: which ones are working, which are waiting on you, and how full each context is. It is read-only and also has a JSON mode, so one coding agent can check on the others.
Overview
agents-top is a top for coding-agent sessions. It finds every Claude Code session and Codex process running on your machine and shows them in one terminal view, so you can see which are working, which are waiting on you, and how full each context is.
It finds agents by their process, then reads whatever local session data it understands. Today only Claude Code transcripts are parsed, so Claude Code sessions get full metrics (context size, tokens, current tool), while Codex gets process information only. Cursor is not supported.
It is read-only: it never writes to transcripts, signals processes, or touches the network. Version 0.1.0 was released in October 2026 under the MIT license. It is also built to be called by coding agents.
Features
Claude Code sessions
- State per session: working now, a tool call waiting, or idle
- Process id, working directory, and a marker for headless (-p) runs
- Model, context size (yellow over 120k tokens, red over 180k), and output tokens
- The tool running now or the last one used, plus Claude Code's own conversation title
- A warning when two sessions have recently driven the shared Chrome browser or computer use
Codex and other providers
- Codex CLI processes (and Codex inside the ChatGPT desktop app) are listed with working directory, uptime, CPU, and sandbox mode
- Codex does not get model, token, tool, or state details yet
- Cursor is not supported
- Also lists any claude remote-control hosts
Guesses are labeled
- State is inferred from when a session's transcript file last changed
- perm? (possible permission prompt) is a guess: a tool call with no result and a transcript unchanged for over 60 seconds, which a slow build also looks like
- Matching a process to its transcript can be swapped when two sessions start in the same directory, and is marked with an approximate sign
- These are labeled in --help and in the JSON schema
Works with coding agents
- --json prints one snapshot in a versioned schema (schemaVersion 1)
- Results go to stdout and diagnostics to stderr
- Exit codes: 0 success (including when no agents are running), 1 runtime error, 2 usage error
- No color, prompt, or live view when stdout is not a terminal
- Includes a SKILL.md that tells an agent when and how to use it
Technical Details
Usage
agents-top prints one snapshot, agents-top -w gives a live view refreshed every 2 seconds, and agents-top --json is for scripts. It needs Node.js 18 or later on macOS or Linux, has no dependencies, and also runs under Bun.
Testing
92 tests run on synthetic transcripts, plus an end-to-end run. No real transcripts are used, since they contain prompts, file contents, and paths.