agtop CLI
A top-style terminal dashboard for Claude Code and Codex sessions: spend, tokens, context load, processes and tool calls.
- 287 ★ on the repository
- Last commit
- GPL-2.0
Extended access
Why this level
- Reads local session transcripts and the process list through `ps` and `lsof`.
- The `d` key deletes finished sessions from disk after confirmation.
- Fetches current model prices from the network (LiteLLM).
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/agtopDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads local session transcripts and the process list through `ps` and `lsof`.
- The `d` key deletes finished sessions from disk after confirmation.
- Fetches current model prices from the network (LiteLLM).
This is third-party code. Review the repository files before installing.
What it does
agtop gathers every Claude Code and Codex session on the machine into one terminal window. Sessions are found in `~/.claude/projects/` and `~/.codex/sessions/`. Each one shows cost under the chosen plan, context fill (CTX%), CPU load and tool-call counts. Panels at the bottom switch with keys `1`–`7`: session info, performance, processes, tool activity, subagents, cost and configuration (CLAUDE.md, memories, skills, MCP servers, permissions). The `-l` and `-j` modes print a table or full JSON for scripts.
Who it is for. People running several Claude Code and Codex sessions at once who want to see token spend and load without opening each one.
Good fit when
- Three sessions run in parallel and it is unclear which one spends money fastest.
- An agent context is filling up and you want to see CTX% before answer quality drops.
- A long build inside a session loads the CPU and you need the child process tree with memory.
- Your own spend report needs a JSON export of sessions.
Not a fit when
- You need to control an agent or change its settings: agtop only displays data.
- You work with agents other than Claude Code and Codex: the panel does not find their sessions.
- Cost will be reconciled with an invoice to the cent: prices come from the LiteLLM list, so it is an estimate.
Example request
Run agtop in a separate tab, find the session with the highest cost over the last day and show token usage by model.Limitations
Data comes from Claude Code and Codex JSONL transcripts, so sessions of other agents are not visible. Cost uses LiteLLM prices (cached for 24 hours) and stays an estimate; the `--plan` flag sets the subscription plan. agtop maps processes to sessions through `ps` and `lsof`. The `d` key deletes the selected finished session after confirmation, so press it carefully in a shared environment. Node.js 18 or newer is required. The GPL-2.0 license sets conditions on embedding the code in your own products.
How to disable. Quit agtop with `q` or `F10`. A global install is removed with `npm uninstall -g @ldegio/agtop`.
FAQ
Which agents does agtop see?
Claude Code and Codex. Sessions are searched in `~/.claude/projects/` and `~/.codex/sessions/`.
How do I get data for a script?
`agtop -j` prints full JSON and `agtop -l` prints a table. The program exits after printing.
How do I count spend under a subscription instead of retail prices?
Pass `-p <plan>`. The default plan is `retail`; the README also mentions Max and included.
How do I show only running sessions?
Turn on the Live filter with `` ` `` or `Shift+Tab`. The list then shows CPU load and spend rate.
How do I install agtop permanently?
Run `npm install -g @ldegio/agtop` and the `agtop` command stays available. `npm uninstall -g @ldegio/agtop` removes it.
Discussion
No questions or reviews yet.
Related
CLI toolsTerminal monitor for Claude Code sessions: busy state, remaining context, memory, processes and sessions waiting for you.
A dashboard for every Claude Code session on the machine: live agents, cost, history search and MCP tools for Claude.
A local real-time dashboard for Claude Code and Codex sessions: agent activity and tool calls
A local dashboard for many Claude Code sessions: each job gets its own context and todo, agents spawn child agents and message each other
A tmux-based TUI that runs Claude Code, Codex and other agents in one list: status, quick prompts, worktrees and diff review
A local control panel for coding agents: it runs Claude Code and Codex, keeps a task queue and merges verified work into main.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| agtop (this card) | no | 287 | |
| ccusage | no | 19,337 | prints token and cost reports for a period; agtop keeps a live dashboard with processes and subagents |
| Claude Code Agent Monitor | no | 1,145 | a local session monitoring dashboard; agtop runs inside the terminal in top style and opens each session configuration |
README in short
The dashboard reads agent transcripts, takes model prices from LiteLLM and maps processes to sessions. No dependencies beyond Node.js.