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.

A real recording — play it in a terminal with asciinema play docs/assets/demo.cast.

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

cctop runs on Linux, including WSL. It reads Linux process tables and drives agents over ptys and unix sockets; there is no macOS or Windows build.

curl -fsSL https://raw.githubusercontent.com/flolep2607/cctop/main/install.sh | sh

That works out your architecture, fetches the right archive, checks it against the checksum the release publishes, and puts the binary on your PATH — /usr/local/bin when you can write there, ~/.local/bin when you cannot, with a line to add to your profile if that one is not on it already. It asks for sudo only when the install genuinely needs it.

Prefer to do it by hand? A release is one statically linked archive, x86_64 or aarch64, holding a single file called cctop:

d=$(mktemp -d)
curl -fsSL https://github.com/flolep2607/cctop/releases/latest/download/cctop-x86_64-unknown-linux-musl.tar.gz | tar xz -C "$d"
sudo install -m755 "$d/cctop" /usr/local/bin/cctop && rm -rf "$d"

Swap in cctop-aarch64-unknown-linux-musl.tar.gz on aarch64. The -C "$d" carries its weight: it unpacks into a temporary directory rather than into whatever directory you happen to be standing in, and without it this stops at Cannot open: File exists for anyone running it inside a cctop checkout, because the crate directory is already named cctop.

Or with cargo — binstall fetches the release binary, install compiles it:

cargo binstall cctop   # or: cargo install cctop

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. The keys worth knowing before anything else:

A tab is a real terminal: type into it, split it with Alt+v/Alt+s, drag it along the bar. Right-click a tab — or press Alt+r — to give it a name and a colour, which every cctop on the machine then shows. Once there are more tabs than digits, Alt+t picks one from a list you narrow by typing, and Alt+b jumps straight to whichever agent is waiting on you — or, when none is, to one whose turn ended while you were looking elsewhere. Alt+z zooms a pane over the whole tab and back.

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, and turns to a ✓ when a turn ended while you were looking at something else — the ones with news. 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.

And it can tell you what the money bought. cctop optimize finds the reads into node_modules, the files fetched again after a compaction, and the tool calls that failed and were billed anyway — each with what it cost and whether that figure was measured or estimated. cctop compare puts your models side by side on your own work: how often each got a file right first time, what a changed file cost and how long it took — --rate 60 prices that time too. See what it cost you for. cctop yield asks the repository what became of it: which sessions' work is on the default branch, which was left on a side branch, and which was never committed. See did the spend ship.

And it remembers for your agents. cctop recall "why is the cache sharded" returns the passages of past sessions — Claude Code, Codex, OpenCode, any of them — that discussed it, ranked by their words and their meaning. cctop --install-mcp gives the same to the agents themselves, so one picks up a decision another made last week instead of re-deriving it. See letting agents see each other.

And it can do all the watching in a browser. cctop serve streams the same table to a page — useful on a phone, where the sessions waiting on you can find you — and gives every session a report that says which tool calls it kept retrying, where its context window went, and what each model cost. Read-only, loopback by default. See In a browser.

• Reading the table — every column, the status dot, filtering, and the full key list
• What it cost you for — cctop optimize and cctop compare, and how honest each figure is
• Did the spend ship — cctop yield, which sessions' work reached the default branch, and how a commit is matched to a session
• What the subscription bought — cctop burn, and why an unused allowance is a ceiling rather than a measurement
• Driving agents — typing into sessions, resuming, tabs and splits, notifications, handoff
• In a browser — cctop serve, the session report, and reaching it from a phone
• 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
• Provider by provider — what each harness records, where its sessions live, and which columns it can fill
• Integrations — agent hooks, the MCP server, and --host
• Troubleshooting — cctop doctor and the usual causes

Two directories of other people's documentation, mirrored so a format change can be read against a copy that does not move: the harnesses cctop reads, and rmux, the multiplexer it hands agents to.

Which agents it reads

A ─ is a gap in what that harness records, not in cctop — the details are on each provider's 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 --statusline    # one line for a status bar: "3 working · 1 waiting · $4.12/h"
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 serve           # the same table in a browser, on a port or a phone
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. If you are sending a pull request, name it after what changes for someone using cctop: the title becomes the release note that cctop --update prints, and CLAUDE.md — which applies to coding agents as much as to people — says what reads well there and what does not.

License

MIT.