cltop

Terminal dashboard that monitors all running Claude Code, Claude.app, and Cowork sessions from a single pane.

Running multiple Claude sessions with no visibility into what each one is doing, how much context it has consumed, or what it costs? cltop discovers Claude processes automatically and displays live status, token usage, task progress, and tool call history in a Textual TUI.

When to use cltop

• You have 2+ Claude Code sessions running and need to see which ones are active, idle, or blocked waiting for input.
• You want to track API spend across sessions against a monthly budget.
• You need to kill a runaway Claude session without hunting through terminal tabs.
• You want to watch tool call history (Read, Edit, Bash, Grep) in real time to understand what a session is doing.

Install

pip install cltop
cltop

Zero configuration. If any Claude process is running, cltop finds it.

For richer session data (exact task descriptions, file context, precise token counts):

cltop install-hook

This registers a PostToolUse hook in ~/.claude/settings.json. Restart running Claude Code sessions for the hook to take effect.

What you see

The TUI has three regions:

Fleet table (top) -- One row per discovered session showing PID, project name, status indicator (active / thinking / idle / blocked / background), token count, and time since last activity.

Metrics bar (middle) -- Three progress bars for the selected session: context window usage (tokens used vs max), task progress (completed vs total), and rate or cost (requests/hr for Max plan, dollars vs budget for API plan).

Detail panel (bottom) -- Project path, git branch, current task description, and a scrolling log of recent tool calls with timestamps.

An SVG recording of the TUI exists in the repository (demo.svg).

Two-layer architecture

Layer 1: Passive discovery (no setup) Finds Claude processes via ps / psutil, then reads session transcripts from ~/.claude/projects/ to extract status, token estimates, tool call history, and task progress. Works immediately.

Layer 2: Hook enrichment (optional) A PostToolUse hook (cltop install-hook) writes structured JSON status files to ~/.claude/fleet/ on every tool call. This adds: exact task descriptions, current file being edited, precise token counts, and TodoList-derived progress tracking. The hook is a bash script that requires jq.

CLI reference

Keybindings

Data model

Each discovered session tracks:

Plan detection: Claude Code CLI, Claude.app, and Cowork sessions default to Max plan (rate-tracked). Unknown sources default to API plan (cost-tracked).

Requirements

• Python 3.11+
• macOS or Linux (relies on ps and Unix process model)
• Runtime dependencies: textual (>=0.50), psutil (>=5.9), watchfiles (>=0.20)
• Optional: jq (required by the Layer 2 hook script)

Status: alpha (v0.1.0)

Works now:

• Automatic discovery of Claude Code CLI, Claude.app, and Cowork sessions
• JSONL transcript parsing for status, tokens, tool history, and task progress
• TUI with real-time updates (3-second poll interval)
• PostToolUse hook system for enriched metadata
• Session kill with TOCTOU-safe PID verification
• Atomic config writes with file locking

Known limitations:

• Token estimates are rough without the hook installed (heuristic: ~3.5 bytes per token from JSONL file size)
• Claude.app sessions are more opaque than CLI sessions (less transcript data available)
• No Windows support
• Filesystem polling at 3s intervals (watchfiles integration planned but not yet wired up)
• JSONL discovery caps at 50 candidates to prevent slow directory walks

Security

• The kill command re-verifies that the target PID still belongs to a Claude process before sending SIGTERM (TOCTOU guard).
• Hook status files are written with umask 077 (owner-only).
• Settings.json writes use flock + atomic temp-file rename to prevent corruption from concurrent access.
• Config writes (budget) use atomic temp-file rename.
• No network calls. All data is local filesystem and process table.

License

MIT