agentop

top, but for your running coding agents — Claude Code, Codex, Grok, Gemini, and Antigravity.

A zero-dependency terminal dashboard that shows every claude (Claude Code), codex (OpenAI Codex), grok (xAI Grok), gemini (Google Gemini), and agy (Google Antigravity) CLI session running on your machine — live, refreshing like top/htop. See at a glance which projects have agents working, what framework and model they're on, which git branch they're on, and what each one is doing right now (running a tool, thinking, or waiting for you).

Usage

No install needed — run it with npx:

npx agentop

Or install globally with npm:

npm install -g agentop
agentop

…or with Homebrew (macOS/Linux):

brew install ktamas77/tap/agentop

…or with Deno (it's published to JSR and runs TypeScript natively):

deno run -A jsr:@ktamas77/agentop          # run it
deno install -gA -n agentop jsr:@ktamas77/agentop   # install the command

Want to see it without any agents running? Try the demo:

npx agentop --demo

Live keys

Key	Action
q / Esc / Ctrl-C	Quit
s	Cycle the sort column
r	Reverse the sort order
+ / -	Increase / decrease the refresh interval

Options

-d, --interval <sec>   Refresh interval in seconds (default: 2)
-s, --sort <key>       Sort by: cpu, mem, up, idle, project, pid (default: cpu)
-r, --reverse          Reverse sort order
-n, --once             Print a single snapshot and exit (no live UI)
    --json             Print agents as JSON and exit
    --demo             Show fabricated sample agents (no real data)
    --no-color         Disable ANSI colors
-h, --help             Show help
-v, --version          Show version

--once and --json make agentop scriptable:

agentop --json | jq '.[] | select(.state == "working") | .project'
watch -n5 'agentop --once'

Columns

Column	Meaning
PID	OS process id of the agent's CLI session
AGENT	Which framework — claude, codex, grok, gemini, or agy
MODEL	Model the session is using (e.g. opus-4-8, gpt-5.5, grok-4, gemini-3-flash)
PROJECT	Working directory basename of the agent
BRANCH	Git branch the session is on
STATE	working (running a tool) · thinking · replied · waiting · idle · stalled
%CPU	Process CPU usage
MEM	Resident memory
UP	How long the process has been running
IDLE	Time since the last transcript activity
ACTIVITY	What the agent is doing right now (current tool, prompt, …)

How it works

agentop reads only local state — nothing is sent anywhere:

1. It lists running claude, codex, grok, gemini, and agy CLI processes with ps (desktop apps, helpers, and launcher shims are filtered out), and resolves each one's working directory via /proc on Linux or lsof on macOS.
2. It joins each process to its session by working directory:
   • Claude Code → the transcript under ~/.claude/projects/<encoded-cwd>/<session>.jsonl (reads just the tail).
   • Codex → the threads table in ~/.codex/state_*.sqlite (read via the system sqlite3 binary — still zero npm deps), with activity from the thread's rollout file when present.
   • Grok → ~/.grok/sessions/<encoded-cwd>/<id>/ (summary.json for the model, events.jsonl for the current phase).
   • Gemini → ~/.gemini/tmp/<project>/chats/session-*.jsonl.
   • Antigravity → the readable transcript in ~/.gemini/antigravity-cli/brain/<id>/…/transcript.jsonl, matched to the workspace it references.
3. From each it extracts the model, git branch, version, last-activity time, and the current tool call, and renders it all as a top-style table.

The design is a small provider abstraction (src/providers/*), so adding another agent framework is mostly one new file.

Requirements

• Runs on Node.js ≥ 18 or Deno ≥ 2 — the same TypeScript source runs on both (a tiny src/platform.ts abstracts the runtime).
• macOS or Linux (ps, plus lsof on macOS)
• sqlite3 (a standard system binary) is used for Codex live enrichment; if it's missing, Codex agents still show — just without live model/activity.

Changelog

See CHANGELOG.md.

Development

The project is TypeScript, ESM. Deno is the dev toolchain (it runs .ts natively); tsc builds the npm dist/.

deno task start          # run from source
deno task demo           # run the demo
deno test -A             # full test suite
deno fmt && deno lint    # format + lint
deno check main.ts       # type-check
npm run build            # tsc -> dist/ (the npm artifact)
npm run check            # fmt + lint + check + test + build (what CI runs)

src/*.ts is the shared, typed core (one src/providers/<name>.ts per agent framework). Entry points: bin/agentop.js (npm, over the built dist/) and main.ts (Deno). A Husky pre-commit hook runs the same deno fmt/lint/check/ test + tsc build; CI runs a Deno matrix and a Node build/smoke matrix across macOS/Linux.

License

MIT © Tamas Kalman