cctop CLI
Terminal monitor for Claude Code sessions: busy state, remaining context, memory, processes and sessions waiting for you.
- 148 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Reads local Claude Code files and ends the selected process with `SIGTERM` on command.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/cctopDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads local Claude Code files and ends the selected process with `SIGTERM` on command.
This is third-party code. Review the repository files before installing.
What it does
`cctop` gathers every running Claude Code session into one table, like `top` for processes: PID, memory, CPU, uptime, context size, model, project, git branch and the last prompt. Busy sessions are green, idle ones red. Sub-agents and child processes appear with open and orphaned TCP ports. The `n` key turns on a bell and desktop notification when a session finishes its turn and waits for you, and `h` opens token usage history by day, model and project. The program reads only `~/.claude` and the process table, and writes its own settings to `~/.claude/cctop/`.
Who it is for. People running several Claude Code sessions in terminals or IDEs who lose track of which one is waiting.
Good fit when
- Ten Claude Code windows are open and it is unclear which one finished its turn.
- A session runs for a long time and its remaining context needs watching.
- A dev server is still holding a port after the agent was closed.
- Token usage for the week is reviewed by model and project.
Not a fit when
- Work happens in a single session and the table adds nothing.
- Sessions run on another machine: the tool reads the local `~/.claude` and process table.
- A process manager with automatic restart is wanted: `cctop` shows sessions and ends them on command.
Example request
Show every Claude Code session as one JSON snapshot and name the ones idle and waiting for input.Limitations
The tool works only with Claude Code and reads its local files in `~/.claude`; other agents do not appear in the table. The `x` key sends `SIGTERM` to the selected session and `f` frees ports left by a dev server, so read which process is selected before confirming. OSC 9 notifications work in iTerm2, Ghostty, kitty, WezTerm and Windows Terminal. Subscription limits show up only after `cctop --capture-usage` is added to the Claude Code status-line script. The install script targets macOS and Linux.
How to disable. Remove the binary: `rm ~/.local/bin/cctop`, or `brew uninstall stefanprodan/tap/cctop` for Homebrew. If limits were enabled, drop the `cctop --capture-usage` line from the status-line script; delete the `~/.claude/cctop/` settings directory by hand.
FAQ
How do I see which session is waiting?
Press `n`: when a session finishes its turn, cctop rings and shows a notification, and the session gets a hollow circle for 30 seconds. The `b` key jumps to the session that rang last.
How do I get data for a script?
`cctop --json` prints full session details and `cctop --once` renders one frame and exits. When piped, the output is also a single frame.
How do I show subscription limits?
Add `printf '%s' "$input" | cctop --capture-usage || true` to the Claude Code status-line script. The 5-hour and 7-day values are saved to `~/.claude/cctop/usage.json`, which the interface reads.
How do I hide extra columns?
List the wanted ones under the `columns` key of `~/.claude/cctop/settings.json`, for example `["project", "branch", "last-action", "prompt"]`. The first seven columns always stay.
Does the program update itself?
No, updating is run with `cctop upgrade`, and `cctop upgrade --check` only reports a newer version.
Discussion
No questions or reviews yet.
Related
CLI toolsA top-style terminal dashboard for Claude Code and Codex sessions: spend, tokens, context load, processes and tool calls.
A dashboard for every Claude Code session on the machine: live agents, cost, history search and MCP tools for Claude.
A local real-time dashboard for Claude Code and Codex sessions: agent activity and tool calls
A local dashboard for Claude Code sessions: timelines, token costs, tools, agents, skills and live sessions
An environment for Claude Code that keeps context across sessions via hooks, ledgers and handoffs, orchestrates agents and saves tokens
A terminal app for running several Claude Code, Codex, Gemini CLI and Aider sessions in parallel, each in its own tmux session and git worktree
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| cctop (this card) | no | 148 | |
| Claude Code Agent Monitor | no | 1,152 | claude-code-agent-monitor shows agent activity and tool calls in a local dashboard; cctop gives a process table of sessions with context, ports and a bell |
| ccusage | no | 19,337 | ccusage reports tokens and cost from logs; cctop watches live sessions and processes |
README in short
The interface spawns no processes: it reads Claude Code files and the process table. The one exception is the explicit `cctop upgrade` command, which replaces its own binary.