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), 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
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)
K	Kill ALL agents
o / e / t	Open dir in Finder / editor / terminal
n	Toggle notifications
?	Help
q	Quit

Mouse: click to select, scroll to navigate.

---

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