cctop

Languages: English · 中文

Real-time terminal dashboard for Claude Code and Codex CLI. Tracks token usage, model breakdown, subscription limits, and USD cost — zero intrusion, read-only on local session logs.

Think htop, but watching ~/.claude/projects/**/*.jsonl and ~/.codex/sessions/**/*.jsonl.

Features

• Live tail of local jsonl session logs; refreshes as new messages append
• Aggregates across session / model / time window dimensions
• Splits five token classes: input / output / cache read / cache write (5m & 1h)
• Price table pulled live from LiteLLM — covers 100+ models across Anthropic / OpenAI / Gemini / Mistral / Bedrock / Vertex, cached locally for 24h
• USD cost computed per session and per model
• Subscription usage % (5h / 7d rolling windows) via Claude Code's official statusline hook — one-time setup, see below
• Codex CLI support — auto-tails ~/.codex/sessions/, no config needed

Install & Run

npm install -g @mimimile/cctop
cctop init       # one-time setup: writes statusline hook to ~/.claude/settings.json
cctop            # launch TUI

Or run without installing:

npx @mimimile/cctop

From source

git clone https://github.com/mimimile/cctop.git && cd cctop
pnpm install
pnpm dev               # launch TUI via tsx
pnpm dev -- --once     # one-shot summary
pnpm build && pnpm link --global   # expose `cctop` globally

Subcommands

cctop                  # launch TUI (default)
cctop status           # same as above, explicit form
cctop init             # write statusLine hook to ~/.claude/settings.json (with backup)
cctop status-hook      # stdin JSON → snapshot file; called by Claude Code statusline

cctop init flags: -f, --force overwrites an existing non-cctop statusLine (still backs up first); --command <cmd> overrides the default "cctop status-hook" (use an absolute path if cctop is not on PATH).

Options for status / default

Flag	Description
-r, --root <path>	Claude project root, defaults to ~/.claude/projects
--once	Print a single summary, skip TUI
--no-remote-prices	Skip LiteLLM fetch, use src/pricing/local.ts fallback only
-V, --version	Print version
-h, --help	Help

Env vars: CCTOP_DEBUG=1 prints price-table fetch logs to stderr.

Wire up subscription usage % (recommended)

Claude Code passes rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage to your statusline command via stdin JSON.

Quick path (after npm i -g @mimimile/cctop):

cctop init       # writes statusLine to ~/.claude/settings.json, backs up any existing file

Then run any prompt in Claude Code once (the rate_limits field only appears after the first API response). Launch cctop and you'll see 5h / 7d progress bars with reset countdowns.

Manual path — edit ~/.claude/settings.json yourself:

{
  "statusLine": {
    "type": "command",
    "command": "cctop status-hook"
  }
}

If cctop is not on PATH, use an absolute path: "command": "node /absolute/path/to/cctop/dist/cli.js status-hook".

Field reference (from the Claude Code statusline docs):

• rate_limits.five_hour.used_percentage — 0–100, 5h rolling window
• rate_limits.five_hour.resets_at — Unix epoch seconds, reset timestamp
• rate_limits.seven_day.* — same shape, weekly window
• Visible only to Claude.ai Pro/Max subscribers; API key users do not get these fields

cctop persists each hook payload to ~/.cache/cctop/usage.json. The TUI watches that file live.

Data sources

Claude Code writes each session to ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. Every assistant message carries a message.usage block:

{
  "input_tokens": 3,
  "cache_creation_input_tokens": 6946,
  "cache_read_input_tokens": 10836,
  "output_tokens": 399,
  "cache_creation": {
    "ephemeral_1h_input_tokens": 6946,
    "ephemeral_5m_input_tokens": 0
  }
}

cctop parses these fields and prices them via the rate table.

Price table

Fetched once at startup from LiteLLM's open JSON, cached at ~/.cache/cctop/prices.json (24h TTL). Mirror order: jsDelivr → fastly → GitHub raw. Any one succeeding is enough.

If all mirrors fail, cctop falls back to src/pricing/local.ts (hard-coded Opus 4.5+ / Sonnet 4.x / Haiku 4.5).

Note: Anthropic dropped Opus pricing from $15/$75 to $5/$25 per MTok starting with Opus 4.5. The remote table reflects this; the local fallback is updated too.

Codex support

The Codex CLI (OpenAI's codex-cli) writes rate_limits directly into ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl as event_msg.token_count events. cctop auto-tails this directory — no configuration required.

Fields:

• rate_limits.primary — usually the 5h window (window_minutes: 300)
• rate_limits.secondary — usually the 7d window (window_minutes: 10080)
• rate_limits.plan_type — plus / pro / team, etc.
• info.total_token_usage — cumulative input / output / reasoning / cached tokens

After launching cctop, you'll see Claude Code and Codex 5h/7d bars side by side.

Roadmap

• Claude Code statusline hook integration (live 5h/7d usage %)
• Codex CLI support (parse ~/.codex/sessions/*.jsonl)
• Historical trend charts (day / hour bars)
• Multi-device aggregation (optional cloud sync)
• Rate-limit event timeline (history of rate_limit errors)

Contributing

Issues and PRs welcome. Please run pnpm typecheck before submitting.

License

MIT