Live terminal monitor for Claude Code token usage.
cctop watches Claude Code's session JSONL files in real-time and displays per-project token rates, costs, and activity trends in an interactive TUI -- think top(1) for your Claude Code spend.
- Live monitoring via inotify filesystem notifications -- no polling
- Hierarchical tree view: projects > sessions > subagents, expandable with Enter
- Per-row sparkline showing each project's activity trend over the window
- Stacked bar histogram on the lower half with color-coded token types (steel blue = input, teal = output, gray = cache)
- Configurable sliding window: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 24h
- Wall-clock-quantized bucketing so the chart slides smoothly instead of jittering
- Fast startup: skips files untouched for 24h and tail-reads the rest, growing each tail just enough to cover the window — sessions with hundreds of megabytes of history don't slow it down
- Live pricing: Claude rates from LiteLLM's pricing database, cached for
24h under
~/.cache/cctop/, merged on top of a built-in fallback table; tiered >200k pricing, 5m/1h cache-write rates, and fast-mode multipliers - Accurate counting: upstream-ccusage dedup semantics — streamed partial writes, sidechain replays, and progress-wrapped subagent records all collapse to the most complete copy
- Keyboard-driven: vim-style navigation (hjkl), sort cycling, collapse all
- Rust toolchain (1.85+ for edition 2024) -- install via rustup
- Claude Code installed and used at least once (cctop reads its session
files from
~/.claude/projects/) - Linux (uses inotify for file watching; macOS support via kqueue is
untested but may work through the
notifycrate)
git clone https://github.com/olofj/cctop
cd cctop
cargo install --path .This installs the cctop binary to ~/.cargo/bin/, which should be in your
PATH if you installed Rust via rustup.
git clone https://github.com/olofj/cctop
cd cctop
cargo build --release
# Binary at ./target/release/cctopYou can copy or symlink the binary wherever you like:
cp target/release/cctop ~/.local/bin/Just run cctop while Claude Code is active in another terminal:
cctopIt will immediately show all projects with token activity from the last 24 hours, and update live as new API responses come in.
cctop [OPTIONS]
Options:
-w, --window <WINDOW> Initial time window [default: 5m]
Values: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 24h
(anything else is an error)
-p, --project <PROJECT> Filter to projects matching this substring
(hyphenated names match too: Claude encodes '/'
as '-' in project dir names, so "my-app" displays
as "my/app" — the filter accepts either form)
--list-projects List all discovered projects and exit
--tick-rate <MS> UI refresh interval in milliseconds [default: 3000]
-O, --offline Use built-in pricing only (skip the LiteLLM
fetch and cache)
-h, --help Print help
-V, --version Print version
# Monitor with a 1-hour window
cctop -w 1h
# Only show projects with "myapp" in the path
cctop -p myapp
# See what projects Claude Code knows about
cctop --list-projects
# Full day view
cctop -w 24hThe top half shows a table with one row per project:
- PROJECT -- decoded filesystem path of the project
- TREND -- sparkline of token activity over the window (oldest left, newest right)
- SESS -- number of active sessions in the window
- MODEL -- the model consuming the most cost in the window
- IN/min -- input tokens per minute (prompt tokens sent to the API)
- OUT/min -- output tokens per minute (response tokens from the API)
- $/min -- estimated cost per minute based on the model pricing table
- $TOTAL -- total cost for this project within the current window
- LAST -- time since the last API response
The bottom half shows a histogram of total token activity over the window, color-coded by token type (steel blue = input, teal = output, gray = cache).
Projects can be expanded with Enter to show individual sessions, and sessions can be expanded further to show subagent activity.
| Key | Action |
|---|---|
q / Esc |
Quit |
↑ ↓ / j k |
Navigate rows |
Enter / Space |
Expand/collapse project or session |
← → / h l |
Shrink/grow time window |
s |
Cycle sort column ($/min, IN/min, OUT/min, Last, Project) |
S |
Reverse sort direction |
d |
Hide selected project from the table |
u |
Unhide all hidden projects |
c |
Collapse all expanded rows |
g / G |
Jump to top/bottom |
PgUp / PgDn |
Scroll by page |
Ctrl-C |
Quit |
Claude Code stores per-session token usage in JSONL files under
~/.claude/projects/. cctop discovers these files, tail-reads recent entries
on startup, then uses inotify to watch for new data in real-time. Each JSONL
line containing input_tokens is parsed (including type:"progress" wrapper
lines from subagent transcripts), costed, and merged into a deduplicated
time-windowed in-memory store; a more complete duplicate arriving later
replaces its sibling so rates correct themselves retroactively. The TUI
re-renders on each tick (3s by default) and immediately after input.
Pricing comes from LiteLLM's community pricing database: a copy is cached
under ~/.cache/cctop/litellm-pricing.json and refreshed when older than
24h, so startup never waits on the network when the cache is fresh; if the
network is down a stale cache is used, and a small built-in table covers
current models as the offline floor (it also covers models LiteLLM doesn't
list yet). Records whose model has no pricing entry count as $0 and the
model names are reported when cctop exits.
This project would not exist without ccusage by @ryoppippi -- the original Node.js CLI tool for analyzing Claude Code token usage. cctop's data format understanding, pricing table, file discovery logic, and cost calculation are all derived from a Rust port of ccusage. Thank you for building the tool that made this possible.