A terminal UI for monitoring and managing AI coding agent sessions. Think htop, but for your Claude Code and Codex CLI processes.
Track CPU, memory, token usage, context window saturation, rate limits, compaction events, active branches, and more — all from a single terminal pane.
- Multi-agent support — monitors both Claude Code and Codex CLI sessions simultaneously
- Real-time process monitoring — CPU, memory, status, uptime for every agent session
- Context window tracking — visual bar showing input, cache, output, and free context
- Compaction detection — flags when an agent compacts its context window (↻ indicator)
- Rate limit monitoring — shows Claude and Codex rate limit quota usage in the status bar
- Token activity waveform — real-time braille sparkline in the header showing aggregate token pulse
- Cost estimation — per-session and total API cost based on model pricing (Claude + OpenAI models)
- Sparkline graphs — inline CPU/memory trend charts using Unicode block characters
- Token breakdown — input, output, cache creation, and cache read token counts per session
- Session metadata — model, branch, slug, session ID, service tier, version
- Two view modes — list view (table) and pane view (card grid)
- Live log tailing — stream session conversation in a split pane (
L) - Session search — full-text search across conversation content (
F) - Aggregate dashboard — total tokens, cost, and context stats across all sessions (
d) - Historical tracking — 24-hour usage charts persisted to disk (
H) - Process control — kill individual or all sessions (graceful
SIGTERMor forceSIGKILL) - Quick-jump — open project directory in Finder (
o), editor (e), or terminal (t) - Desktop notifications — get notified when a session completes (macOS/Linux)
- Vim-style navigation —
hjkl,g/G, arrow keys, plus mouse support - Sort & filter — sort by CPU, memory, context %; filter by branch, model, directory, or slug
- Color themes — 5 built-in themes (default, minimal, dracula, solarized, monokai) + custom
- Braille context bars — sub-character precision context visualization (configurable)
- Plugin system — extend with custom columns via
~/.ctop/plugins/ - Configurable — refresh interval, context limit, default view, themes via
~/.ctoprcor CLI flags - Cross-platform — macOS, Linux, and Windows
- Zero dependencies — pure Node.js, no
npm installrequired - Auto-refresh — configurable interval (default 5s)
brew tap aakashadesara/ctop
brew install ctop-claudenpm install -g ctop-claude
ctopOr run without installing:
npx ctop-claudegit clone https://github.com/aakashadesara/ctop.git
chmod +x ctop/claude-manager
ln -s "$(pwd)/ctop/claude-manager" /usr/local/bin/ctopcurl -o /usr/local/bin/ctop https://raw.githubusercontent.com/aakashadesara/ctop/main/claude-manager
chmod +x /usr/local/bin/ctopctopIf no agent processes are running, you'll see an empty state. Start a Claude Code or Codex CLI session and ctop will pick it up on the next refresh.
Add these to your ~/.zshrc or ~/.bashrc:
# Launch ctop
alias ctop="/usr/local/bin/ctop"
# Quick-kill all Claude sessions (no TUI, just nuke them)
alias ckill="pkill -f 'claude'"Then reload:
source ~/.zshrc| Key | Action |
|---|---|
↑ / k |
Move selection up |
↓ / j |
Move selection down |
← / h |
Move left (pane mode) |
→ / l |
Move right (pane mode) |
g |
Jump to first process |
G |
Jump to last process |
P |
Toggle list / pane view |
s |
Cycle sort: age → cpu → mem → context |
S |
Reverse sort order |
/ |
Start filter (type to search, Enter to confirm) |
F |
Full-text search session conversation content |
ESC |
Clear filter/search (or quit if none active) |
r |
Refresh process list |
x |
Kill selected process (SIGTERM) |
X |
Force kill selected process (SIGKILL) |
K |
Kill ALL agent processes |
A |
Kill all stopped/zombie processes |
o |
Open project directory in file manager |
e |
Open project directory in editor |
t |
Open new terminal in project directory |
d |
Toggle aggregate dashboard |
L |
Toggle live log tailing split pane |
H |
Toggle 24-hour usage history view |
T |
Cycle color theme |
n |
Toggle desktop notifications |
? |
Show help |
q |
Quit |
Mouse support: click to select, scroll wheel to navigate.
The context bar shows how much of the 200k token window is consumed:
[████████░░░░░░░░░░░░░░░░░░░░░░] 27% used
▲ green ▲ blue ▲ cyan ▲ yellow ▲ gray
input cache-w cache-r output free
Color coding:
- Green — 70%+ free (healthy)
- Yellow — 40–70% free
- Orange — 10–40% free (getting tight)
- Red — <10% free (near limit)
On wide terminals (140+ cols), a detail pane appears showing full session info: model, branch, slug, token breakdown, turn duration, session ID, and more.
ctop --refresh 3 # Refresh every 3 seconds
ctop --context-limit 128000 # Set context window to 128k
ctop --pane # Start in pane/grid view{
"refreshInterval": 5000,
"contextLimit": 200000,
"defaultView": "list",
"theme": "default",
"contextBarStyle": "block",
"notifications": {
"enabled": true,
"minDuration": 30
}
}| Option | Values | Description |
|---|---|---|
refreshInterval |
milliseconds | How often to refresh (default: 5000) |
contextLimit |
tokens | Context window size (default: 200000) |
defaultView |
"list" / "pane" |
Starting view mode |
theme |
"default" / "minimal" / "dracula" / "solarized" / "monokai" |
Color theme |
contextBarStyle |
"block" / "braille" |
Context bar rendering style |
notifications.enabled |
boolean | Desktop notifications on session completion |
notifications.minDuration |
seconds | Minimum session duration to trigger notification |
CLI flags override config file values.
- macOS, Linux, or Windows (uses
ps+lsofon macOS,ps+/procon Linux, PowerShell on Windows) - Node.js 18+
- Claude Code and/or Codex CLI installed and running sessions
On Windows, ctop uses PowerShell to detect Claude processes and retrieve process information. Process working-directory detection is limited compared to macOS/Linux -- ctop will fall back to the executable path when the true CWD is unavailable. Kill uses taskkill, file explorer uses explorer, and terminal opens cmd. Notifications use a PowerShell MessageBox popup.
ctop reads process info from ps (or PowerShell on Windows), resolves working directories via lsof (or Get-CimInstance on Windows), and enriches each process with session metadata by parsing local session files:
- Claude Code:
.jsonlsession files in~/.claude/projects/ - Codex CLI:
.jsonlrollout files in~/.codex/sessions/
No network calls. No external dependencies. Everything stays local.
Extend CTOP with custom columns and detail rows. Create .js files in ~/.ctop/plugins/:
// ~/.ctop/plugins/my-plugin.js
module.exports = {
name: 'my-plugin',
column: {
header: 'CUSTOM',
width: 10,
getValue: (proc) => proc.cwd ? 'yes' : 'no',
},
};See examples/plugins/uptime.js for a complete example.
- Linux support —
ps+/procbased process detection - npm package —
npm install -g ctop-claude - Configurable settings — refresh interval, context limit, default view
- Sort & filter — sort by age/CPU/memory/context, filter by branch/model/dir
- Windows support — PowerShell-based process detection
- Homebrew formula —
brew install ctop-claude - Cost estimation — per-session and aggregate API cost tracking
- Sparkline graphs — inline CPU/memory trend visualization
- Live log tailing — stream session conversation in split pane
- Session search — full-text search across conversation content
- Aggregate dashboard — totals across all sessions
- Historical tracking — 24-hour usage charts
- Desktop notifications — notify on session completion
- Quick-jump — open project in Finder/editor/terminal
- Mouse support — click to select, scroll to navigate
- Color themes — 5 built-in + custom theme support
- Braille context bars — sub-character precision rendering
- Plugin system — custom columns via
~/.ctop/plugins/ - Modular codebase — split into
src/modules - Codex CLI support — monitor Codex sessions alongside Claude
- Compaction detection — flag context window compaction events
- Rate limit monitoring — Claude and Codex quota usage in status bar
- Token activity waveform — real-time aggregate token pulse in header
PRs are welcome!
# Fork & clone
git clone https://github.com/<your-username>/ctop.git
cd ctop
# Run directly
./claude-manager
# Run tests
npm testThe codebase is split into modules under src/ with claude-manager as the entry point. Tests are in test/ using Node.js built-in test runner.
Areas where contributions would be especially helpful:
- Windows testing — basic support is in, needs real-world validation
- Linux testing — basic support is in, needs real-world validation
- Performance — profiling on systems with many Claude sessions
Please open an issue first for large changes so we can discuss the approach.
MIT — use it however you want.