CTOP – Terminal Pane for Monitoring AI Agents

Notifications You must be signed in to change notification settings

Fork 8

Star 86

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

178 Commits

178 Commits

.github/workflows

.github/workflows

assets

assets

docs

docs

examples/plugins

examples/plugins

scripts

scripts

skills/ctop

skills/ctop

src

src

test

test

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

claude-manager

claude-manager

package.json

package.json

Repository files navigation

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 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 --json # Full detail on one session ctop log --tail 20 # Last 20 conversation messages ctop search "TODO" --json # Full-text search across sessions ctop diff # 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 # SIGTERM (must be your own user) ctop kill --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 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

About

CTOP - Interactive Process Viewer for AI Coding Agents

ctop.dev/

Topics

tui

terminal-based

codex

ai-agents

claude

claude-ai

claude-code

codex-cli

coding-agent

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

86 stars

Watchers

0 watching

Forks

8 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

JavaScript 97.9%

Shell 2.1%