cctop AGENTS.md

AGENTS.md

Guidance for AI agents and contributors working on cctop, an interactive top-style TUI for monitoring running Claude Code sessions.

What this is

A single Bun/TypeScript program that lists every running Claude Code session with process stats, busy/idle state, context size, model, host app, project, branch, last prompt, a tree of sub-processes, and live sub-agents. On a TTY it's an interactive TUI; piped or with --once it prints one plain-text frame and exits, while --json prints one JSON snapshot and exits.

• Runtime: Bun (TypeScript run directly, no build step for dev).
• Platforms: macOS and Linux only (process table is read via macOS libproc FFI or Linux /proc).
• Read-only, with deliberate exceptions. In its monitoring mode cctop spawns no processes and never mutates any session, registry, or transcript. Its only writes are its own files under ~/.claude/cctop/: the usage cache (usage.json, only under --capture-usage) and the persisted TUI preferences (settings.json, the refresh interval, sort mode, and notifications toggle, written only when the user changes them; the file also carries the hand-edited columns list, which cctop only ever reads — the save merge preserves it); the only thing it ever does to another process is send a signal, and only on an explicit user action (x → SIGTERM a session; f → SIGTERM a session's orphaned dev-server processes to free their ports). Preserve this property. Separate from all of that is one explicit, opt-in mode: the cctop upgrade subcommand (src/upgrade.ts) reaches the network and replaces cctop's own binary. It never runs from the refresh loop — the monitor path never even imports it — so everything that isn't cctop upgrade stays read-only. It is also the only thing that touches the network at all: the monitor makes no network calls, a property docs/usage-limits.md already relies on ("cctop is read-only: it reads ~/.claude and the process table, and makes no network calls") and the reason usage limits arrive through a status-line hook instead of an API call. The TUI's "restart to run the new version" notice preserves that: it stats its own binary (src/binary.ts) to see the file was swapped underneath it, rather than asking GitHub whether a release exists. Polling from the refresh loop would break it.
• Zero runtime dependencies. cctop imports only Bun and OS built-ins (bun:ffi, node:fs, …); package.json has no dependencies field (the devDependencies are just Biome/tsc/types). Do not add npm packages — keep it dependency-free.