cctop

An htop for your AI coding agents. One screen showing every Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi and Windsurf session on your machine — what each is doing, what it has spent, and which one is waiting on you.

 Sessions (4/71)                                            $12.64 today · 2 running

    LAST   DUR        $  CTX%  CPU%   MEM  TOOLS  ERR%  MODEL       PERM    !  PROJECT
 ●    3s  1h12m   $4.82   68%  22.4  1.2G    178    2%  opus-5      edits   ⚠  ~/cctop
 ●   14s    46m   $2.10   31%   8.1  840M     94    ─   gpt-5-codex ask     ⚠  ~/cctop
 ●    2m  2h03m   $9.41   88%   0.0  1.5G    402   14%  opus-5      BYPASS  ·  ~/api
 ○    4h    22m   $0.31    ─     ─     ─      31    0%  sonnet-5    ─       ─  ~/scripts

 Conflict: ⚠ …/ui/mod.rs — 2 agents have written it

It reads what the agents leave on disk, so it sees sessions it did not start, including ones that ended weeks ago. Nothing to configure, nothing to run alongside it.

A Rust rewrite of an earlier Node implementation.

Install

cargo install cctop

Or grab a binary for your platform from the latest release:

# Linux x86_64 (static — works on any distro)
curl -fsSL https://github.com/flolep2607/cctop/releases/latest/download/cctop-x86_64-unknown-linux-musl.tar.gz | tar xz
sudo install -m755 cctop /usr/local/bin/cctop

macOS, Windows, checksums and cctop --update are in Installing cctop.

Start here

cctop

That is the whole first run. It finds your sessions, prices them, and draws the table above.

Four keys are worth knowing before anything else:

Then two commands worth running once:

cctop --install-hooks   # let the agents report their own state, live
cctop doctor            # check the installation and say what is wrong with it

What it tells you

What everything costs. Tokens times published rates, per session, per hour, per day, per model. The numbers are estimates and the cost page is honest about which providers report real figures and which are inferred.

What is in the context window. CTX% says it is 68% full; the Context panel says what is in it — startup, tool output, attachments, and an Unaccounted bar that never pretends to be smaller than it is. Under it, a chart of how the window filled across the whole session, compactions included. See The bottom panels.

Which session needs you. The status dot goes amber when an agent is waiting on input and red on an API error. w turns on the terminal bell and a desktop notification for the moment a session crosses into waiting.

Which sessions are stuck. ERR% is the share of a session's tool calls that failed — a quarter of them is an agent retrying something that will not work and paying for each attempt. Compaction cadence catches the other kind of waste, a session rebuilding a window it keeps refilling.

When two agents are about to collide. Two agents in one checkout is not a merge conflict — git would announce that. It is one of them writing a file the other still holds, and the loser finds out when the work is gone. The ! column says so first. See Reading the table.

What it can do

Beyond watching, cctop can answer an agent (s), reopen any session in a tab of its own (R), hold several agents side by side, hand a session's context over to a different harness (O), and read the sessions on another machine over ssh.

• Reading the table — every column, the status dot, filtering, and the full key list
• Driving agents — typing into sessions, resuming, tabs and splits, notifications, handoff
• The bottom panels — Tool Activity and the context breakdown
• What the cost figures mean — how each provider is priced, and where the data comes from
• Integrations — agent hooks, the MCP server, and --host
• Troubleshooting — cctop doctor and the usual causes

Which agents it reads

Claude for Mac is read too. A ─ is a gap in what that harness records, not in cctop — the details are on the cost page.

A note on cost figures

Most costs are estimates: tokens multiplied by published per-token rates. Subscription plans — Claude Max, Pro, Team — are flat-rate or bundle tokens differently, so these numbers will not match your invoice. Treat the $ column as a measure of resource consumption, not as billing. --plan max displays bundled usage as incl instead.

Usage

cctop                 # interactive UI
cctop --list          # print a table and exit
cctop --json          # dump full session data as JSON
cctop --plan max      # treat Claude usage as bundled
cctop --host devbox   # also show another machine's sessions, read over ssh
cctop doctor          # check this installation and say what is wrong with it
cctop claude          # start an agent on a pty cctop can watch and type into

cctop --help has the rest.

Contributing

Bug reports and patches welcome — see CONTRIBUTING.md, which also has the architecture notes and the things about this codebase that are not obvious from reading it.

License

MIT.