CTOP — AI Agent Terminal Operations Panel

htop for your AI coding agents. Monitor Claude Code, Codex CLI, OpenCode, and Devin sessions — CPU, memory, tokens, context window, costs, branches — from a single terminal pane.

Features

• Multi-agent monitoring — Claude Code + Codex CLI + OpenCode + Devin, real-time CPU/memory/status
• Context window tracking — visual bar with input, cache, output, and free segments
• Cost estimation — per-session and aggregate API cost (Claude + OpenAI pricing)
• Token waveform — real-time sparkline showing token activity pulse
• Two view modes — list view (table) and pane view (card grid), toggle with P
• Live log tailing — stream conversation in a split pane (L)
• Sort, filter, search — by CPU, memory, context, branch, model, or full-text (F)
• Dashboard & history — aggregate stats (d), 24-hour usage charts (H)
• Process control — kill sessions (graceful or force), bulk multi-select close, quick-jump to project dir
• Desktop notifications — get notified when sessions complete
• 5 color themes — default, minimal, dracula, solarized, monokai (+ custom)
• Plugin system — extend with custom columns via ~/.ctop/plugins/
• Compaction & rate limit detection — flags compaction events and quota usage
• CLI mode for agents — ctop ls, ctop whoami, ctop alerts, … (see CLI mode)

---

Installation

# Homebrew
brew tap aakashadesara/ctop && brew install ctop-claude

# npm
npm install -g ctop-claude

# npx (no install)
npx ctop-claude

# From source
git clone https://github.com/aakashadesara/ctop.git
chmod +x ctop/claude-manager
ln -s "$(pwd)/ctop/claude-manager" /usr/local/bin/ctop

Then run ctop. If no agents are running, you'll see an empty state — start a Claude Code, Codex, OpenCode, or Devin session and it'll appear on the next refresh.

---

Keyboard shortcuts

Key	Action
j/k or ↑/↓	Navigate
h/l or ←/→	Navigate (pane mode)
g / G	Jump to first / last
P	Toggle list / pane view
p	Pin / unpin session (sticks it to the top)
Space	Mark / unmark session (multi-select)
Shift+↑/↓ or V	Extend / start a marked range
a	Select all visible / clear
s / S	Cycle sort / reverse
/	Filter
F	Full-text search conversations
d	Toggle dashboard
L	Toggle log pane
H	Toggle 24-hour history
W	Timeline view
T	Cycle color theme
x / X	Kill (SIGTERM / SIGKILL) — bulk if rows are marked
K	Kill ALL agents
A	Kill ALL stopped/dead agents
o / e / t	Open dir in Finder / editor / terminal
n	Toggle notifications
?	Help
Esc	Clear selection (or filter / search)
q	Quit

Mouse: click to select, scroll to navigate, click the ★ gutter to pin/unpin, Shift+click to mark (best-effort).

Pinned sessions

Keep the sessions you care about in view. Press p (or click the ★ in a row's gutter, or the Pin footer button) to pin the session under the cursor — it jumps to a yellow ★ Pinned section at the top and stays there regardless of sort or filter. Pinning works in list, group, and pane views. Pins are keyed by session identity (not pid), so they survive refreshes, the session restarting, and quitting ctop — persisted to ~/.ctop/pins.json. Press p again to unpin.

Bulk actions

Mark several sessions and act on them at once. Press Space to mark the session under the cursor, or hold Shift while pressing ↑/↓ to extend a range; press V for vim-style range mode (then move to extend) and a to select all visible. With sessions marked, x / X close the whole set after a confirmation prompt; Esc clears the selection. Works in list, pane, and group views.

Shift+click note: many terminals (Terminal.app, iTerm2, GNOME Terminal, …) reserve Shift+click for their own text selection and never forward it to the app, so Shift+click marking is best-effort. The keyboard path (Space / Shift+↑/↓ / V) works everywhere.

---

Agent skill

A self-contained ctop skill ships in this repo. Drop it into Claude Code so any agent learns when and how to call ctop:

# Per-project
mkdir -p .claude/skills && cp -r skills/ctop .claude/skills/

# Or user-wide
mkdir -p ~/.claude/skills && cp -r skills/ctop ~/.claude/skills/

Once installed, ask any Claude Code session things like "what other agents am I running", "how much have my sessions cost", "is my context about to compact" — the agent will reach for ctop automatically.

Skill files:

• SKILL.md — trigger sheet + common patterns
• reference.md — full per-command spec
• examples.md — copy-pasteable recipes

CLI mode (for agents and scripts)

ctop with no args starts the interactive TUI. ctop <subcommand> runs a one-shot query and exits, so AI agents can introspect their own sessions and sister sessions from another terminal.

ctop ls                          # Table of every running agent
ctop ls --json                   # Same, machine-parseable
ctop ls --agent claude           # Filter by backend
ctop ls --cwd ~/code/myproj      # Filter by directory

ctop get <pid> --json            # Full detail on one session
ctop log <pid> --tail 20         # Last 20 conversation messages
ctop search "TODO" --json        # Full-text search across sessions
ctop diff <pid>                  # Git diff for the session's cwd
ctop stats --json                # Aggregate cost / tokens / counts

ctop whoami                      # Detect which session you're in
ctop whoami --pid-only           # PID only, for scripting
ctop alerts                      # Low-context / idle / ghost warnings
ctop alerts --severity critical  # Only critical-level alerts

ctop kill <pid>                  # SIGTERM (must be your own user)
ctop kill <pid> --force          # SIGKILL
ctop notify "title" "message"    # Desktop notification

whoami detects the calling session via $CTOP_PID → parent-PID walk → $PWD match, with a matchConfidence label (exact | ppid | cwd-guess | none) so agents know how much to trust the answer.

Read tools surface data that the user could read off disk anyway. kill enforces uid ownership and an agent-session check before sending the signal — there is no kill-all.

Examples

# Find sessions about to compact
ctop ls --json | jq '.[] | select(.contextPct != null and .contextPct < 20)'

# Self-aware compaction (hook)
[ "$(ctop whoami --json | jq -r .session.contextPct)" -lt 15 ] && \
  echo "context low — consider /compact"

# Clean up ghost sessions
ctop alerts --json | jq -r '.[] | select(.kind=="ghost") | .pid' | \
  xargs -I {} ctop kill {} --force

Configuration

CLI flags (TUI mode)

ctop --refresh 3             # Refresh every 3 seconds
ctop --context-limit 128000  # Set context window to 128k
ctop --pane                  # Start in pane view

Config file (~/.ctoprc)

{
  "refreshInterval": 5000,
  "contextLimit": 200000,
  "defaultView": "list",
  "theme": "default",
  "contextBarStyle": "block",
  "notifications": { "enabled": true, "minDuration": 30 }
}

CLI flags override config file values.

---

How it works

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/projects/ for Claude, ~/.codex/sessions/ for Codex) and SQLite databases (~/.local/share/opencode/ for OpenCode, ~/.local/share/devin/cli/ for Devin). No network calls, no external dependencies.

Plugins

Extend with custom columns. Create .js files in ~/.ctop/plugins/:

module.exports = {
  name: 'my-plugin',
  column: {
    header: 'CUSTOM',
    width: 10,
    getValue: (proc) => proc.cwd ? 'yes' : 'no',
  },
};

See examples/plugins/ for more.

---

Requirements

• Node.js 18+
• macOS, Linux, or Windows — Windows uses PowerShell for process detection; CWD resolution is more limited than macOS/Linux.
• Claude Code, Codex CLI, OpenCode, and/or Devin (terminal) running sessions
• sqlite3 on PATH for OpenCode and Devin session reads (built-in on macOS; available via apt/brew on Linux)

Contributing

PRs welcome! Fork, clone, run ./claude-manager to develop, npm test to test. Open an issue first for large changes.

License

MIT