Getting started¶

Install¶

Route	Command	Notes
Homebrew	`brew install kannandreams/tap/agent-top`	macOS and Linux, prebuilt; installs shell completions
Cargo, prebuilt	`cargo binstall agent-top`	downloads the release binary, no compiler needed
Cargo, from source	`cargo install --locked agent-top`	builds from crates.io; needs Rust 1.85 or newer
By hand	the releases page	tarballs and `sha256` for macOS and Linux, x86_64 and arm64

Every route ends at the same single binary: no Python, no Node, no daemon. Without Homebrew, agent-top --completions zsh (or bash, fish) prints a completion script to source from your shell's startup file.

First run¶

agent-top

That is the whole setup. Start it in any terminal while your agents run. It finds Claude Code, Codex, Gemini CLI and OpenCode sessions on its own, from the process table and the transcripts each harness writes.

If the table is empty, no supported agent is running or has written a transcript in the last 30 minutes. agent-top --json prints everything it found, which is the quickest way to see why a session is missing.

Keys¶

Key	What it does
`j` `k` or arrows	move the selection; the detail pane follows
`Tab` or `v`	switch the detail pane between the process tree and the tool trace
`t` or `Enter`	show or hide the detail pane
`s` `r`	cycle the sort column, reverse it
`x`	hide stopped sessions (shown only when there are some)
`p` or `Space`	pause refresh
`l`	slowest tools, across every agent
`f`	failed tool calls
`a`	advice: oversized results, idle and growing MCP servers
`m`	MCP servers under every agent, and the orphans
`Enter` on a popup	fill the terminal with that panel; `Esc` goes back
`o` on a popup	open that panel in a new tmux, zellij, WezTerm or kitty pane
`?`	help, the version and how to upgrade
`q`	quit

Other ways to run it¶

agent-top --once                  # print the table once and exit
agent-top --json                  # one snapshot as JSON, for scripts and bug reports
agent-top --replay snap.json      # render a saved snapshot, keys and all
agent-top mcp                     # start on the MCP servers panel; also slow, fails, advice
agent-top report --since 7d       # what every harness cost this week
agent-top trace --session 9f2c -o trace.json   # one session as a Perfetto trace
agent-top --interval-ms 500       # faster refresh
agent-top --stopped-window-min 120   # keep stopped sessions visible for two hours
agent-top --theme light           # Catppuccin Latte; dark is Mocha, auto asks the terminal
agent-top --prices                # the price table in use, with your overrides marked
agent-top --whats-new             # this build's changelog, no network call

Colours¶

agent-top uses Catppuccin Mocha on a dark terminal and Catppuccin Latte on a light one. At startup it asks the terminal for its background colour; if the terminal does not answer it reads COLORFGBG, and failing that it uses Mocha. --theme dark or --theme light picks one without asking, and AGENT_TOP_THEME=dark or light in your shell profile does the same for every run. The flag wins over the variable. The theme is chosen once at startup, so restart agent-top after changing your terminal's colours.

Upgrading¶

agent-top checks crates.io once a day for a newer version. Set AGENT_TOP_NO_UPDATE_CHECK=1 to turn the check off. When one is out, the footer badge turns amber and, once per run, a popup asks:

u upgrades now, with the installer that put agent-top here: brew update && brew upgrade agent-top, cargo binstall -y agent-top or cargo install --locked agent-top, judged from where the binary is. The exact command is shown before you press anything. When it finishes, agent-top starts again on the new version with the same arguments.
n or Esc is "not now": that version is not asked about again, the badge stays amber, and the next release asks afresh.

A binary installed by hand is not guessed at: the popup lists the routes and leaves the command to you. This upgrade is the one command agent-top ever runs that changes the machine. It changes only agent-top, and only on that keypress.