cctop

Interactive top-style monitor for Claude Code sessions. Know at a glance what Claude is working on, how much context it has left, and which sessions are waiting for input.

Features

• All your sessions at a glance — every running Claude Code session in one table: process stats (PID, memory, CPU, uptime), busy/idle state, context size, model, host app (terminal or IDE), project, git branch, and last prompt.
• Sub-agent & process tree — live sub-agents (with their latest turn) and each session's sub-processes, open and orphaned TCP ports.
• Live TUI — navigate with the keyboard, open a per-session detail view, and filter and sort on the fly; piped or run with --once it prints a single frame. The sort mode, refresh interval, and notifications toggle are remembered across restarts.
• Get pinged when a session needs you (opt-in) — press n and cctop rings the terminal bell and raises a desktop notification (OSC 9, supported by iTerm2, Ghostty, kitty, WezTerm, Windows Terminal) whenever a busy session finishes its turn and waits for your input — so you can look away while agents run. Works with tmux monitor-bell window flags too.
• Status at a glance — busy sessions are green, idle red; CPU and context heat toward red as they climb; the selected session is marked with a blue bar.
• Weekly usage limits (opt-in) — show your Claude subscription's 5h/7d rate-limit usage in the summary line.
• Quit a runaway session in place (x → SIGTERM, with confirm), or free ports held by a session's leftover dev server (f in the detail view).
• Session history (h) — a dashboard over past sessions: a per-day token-usage chart, recent sessions, and breakdowns by model, tool/MCP, and project.
• Read-only and local — the TUI reads only ~/.claude and the process table, spawns no processes; the only files it writes are its own preferences and usage cache under ~/.claude/cctop/.
• Zero dependencies — a single Bun program with no npm packages; it uses only the Bun runtime and OS built-ins.

Install

On macOS or Linux, install the standalone binary with Homebrew:

brew install stefanprodan/tap/cctop

Or install it as a script with Bun:

bun install -g github:stefanprodan/cctop#v0.5.0

Usage limits (opt-in)

To display the subscription's rate-limit usage, add the following to your Claude Code status-line script:

input=$(cat)

# persist the account-wide 5h/7d rate limits
printf '%s' "$input" | cctop --capture-usage || true

With --capture-usage the rate limits stats are persisted to ~/.claude/cctop/usage.json from which the cctop TUI reads. See docs/usage-limits.md for more details.

Update

With Homebrew:

brew upgrade stefanprodan/tap/cctop

Or upgrade the script to the latest release with Bun:

bun rm -g cctop; bun install -g github:stefanprodan/cctop#v0.5.0

Uninstall

With Homebrew:

brew uninstall stefanprodan/tap/cctop

Or with Bun:

bun uninstall -g cctop

If you enabled usage limits, also remove the cctop --capture-usage line from your Claude Code status-line script.

Usage

On an interactive terminal cctop runs as a live TUI (like top); when piped, redirected, or run with --once it prints a single frame and exits.

Keys

While the TUI is running:

Options

cctop [filter] [options]

  filter                 only show sessions whose project, host, branch,
                         model, or session id contains this
  -w, --watch[=seconds]  set the refresh interval (default: 1s, min 0.25s)
  --once                 render once and exit (default when piped)
  --json                 print full session details as JSON
  -v, --version          show version
  -h, --help             show this help

Examples:

cctop flux         # start filtered to sessions matching "flux"
cctop --watch=0.5  # refresh twice a second
cctop --once       # single frame, then exit
cctop --json       # machine-readable snapshot

Contributing

cctop is open source and contributions are welcome — open an issue or send a pull request on GitHub. See docs/CONTRIBUTING.md to get set up.

License

Apache 2.0