Purpose
ctop is an interactive process viewer for the terminal, positioned as the "htop for AI coding agents." It is used to monitor AI coding agent sessions such as Claude Code, Codex CLI, OpenCode, and Devin in a single terminal pane, helping users keep track of the resource usage and running status of each session in real time.
Main capabilities
- Multi-agent monitoring: Supports Claude Code, Codex CLI, OpenCode, and Devin, displaying CPU, memory, and status in real time.
- Context window tracking: Displays input, cache, output, and idle portions with visualized bars.
- Cost estimation: Estimates API costs per session and in aggregate (based on Claude and OpenAI pricing).
- Token waveform: Real-time sparklines show token activity pulses.
- Two view modes: List view (table) and pane view (card grid), switched with P.
- Real-time log tracking: Stream conversations in a split pane (L).
- Sorting, filtering, searching: Can be done by CPU, memory, context, branch, model, or full text (F).
- Dashboard and history: Aggregate statistics (d), 24-hour usage charts (H).
- Process control: Terminate sessions (gracefully or forcibly), batch multi-select close, quickly jump to the project directory.
- Desktop notifications: Receive notifications when a session completes.
- 5 color themes: default, minimal, dracula, solarized, monokai (custom supported).
- Plugin system: Extend with custom columns via ~/.ctop/plugins/.
- Compaction and rate limit detection: Flag compaction events and quota usage.
- Agent-oriented CLI mode: ctop ls, ctop whoami, ctop alerts, etc.
Usage
Run ctop It starts up. If there are no running agents, an empty state will be shown; after starting a Claude Code, Codex, OpenCode, or Devin session, it will appear on the next refresh.
Keyboard shortcuts and mouse operations: The mouse can be used to click to select, scroll to navigate, click the ★ column to pin/unpin, and Shift+click to mark (best effort).
Pinning sessions: Press p (or click the ★ column in the row, or the Pin button at the bottom) to pin the session under the cursor; it will jump to the yellow ★ Pinned area at the top and remain visible when sorting or filtering. Pinning applies to list, grouped, and pane views. Pinning is keyed by session identity (not pid), so it persists across refreshes, session restarts, and after exiting ctop, stored in ~/.ctop/pins.json. Press p again to unpin.
Batch marking and operations: Press Space to mark the session under the cursor, or hold Shift while pressing ↑/↓ to extend the range; press V to enter vim-style range mode (then move to extend), and press a to select all visible items. After marking, you can run x/X to close the entire group at once, with a confirmation prompt; Esc clears the selection. Applies to list, pane, and grouped views.
About Shift+click: Many terminals (Terminal.app, iTerm2, GNOME Terminal, etc.) reserve Shift+click for their own text selection and do not forward it to the application, so Shift+click marking is best effort. The keyboard paths (Space / Shift+↑/↓ / V) work in all environments.
ctop skill: This repository includes a self-contained ctop skill that can be placed into Claude Code so that any agent learns when and how to invoke ctop. Once installed, you can ask any Claude Code session questions such as "what other agents am I running", "how much have my sessions cost", "is my context about to compact", and the agent will automatically use ctop. The skill includes SKILL.md (trigger table and common patterns), reference.md (complete command-by-command specification), and examples.md (copy-pasteable examples).
CLI mode (for agents and scripts):ctop starts the interactive TUI without arguments;ctop <subcommand> Runs a one-shot query and exits, so an AI agent can introspect its own session and companion sessions from another terminal. whoami detects the calling session via $CTOP_PID → parent PID traversal → $PWD matching, with a matchConfidence label (exact | ppid | cwd-guess | none), so the agent knows how trustworthy the answer is. Read tools display data the user could have read from disk anyway. kill enforces uid ownership and agent-session checks before sending a signal; there is no kill-all.
CLI flags (TUI mode) and config file (~/.ctoprc): CLI flags override config file values.
Data sources: reads process info from ps (PowerShell on Windows), resolves working directories via lsof, and enriches each process with session metadata from local JSONL files (Claude's ~/.claude/projects/, Codex's ~/.codex/sessions/) and SQLite databases (OpenCode's ~/.local/share/opencode/, Devin's ~/.local/share/devin/cli/). No network calls, no external dependencies.
Plugin extensions: create .js files in ~/.ctop/plugins/ to add custom columns. See examples/plugins/ for more examples.
When to use
Suited to developers running multiple AI coding agent sessions at once, for monitoring resource usage, context windows, costs, and session status within a single terminal interface; also suited to AI agents or scripts introspecting session information via CLI mode.
Limitations
Supports macOS, Linux, or Windows; Windows uses PowerShell for process detection, and working directory resolution is more limited than on macOS/Linux. Requires running Claude Code, Codex CLI, OpenCode, and/or Devin (terminal) sessions. Reading OpenCode and Devin sessions requires sqlite3 on PATH (built into macOS; installable on Linux via apt/brew). kill has no kill-all operation, andis constrained by uid ownership and agent-session checks. Shift+click marking may not work in some terminals.
