topagents

htop for AI agents. One screen showing every AI agent running on this machine: Claude Code sessions and their subagents, other agent CLIs (Codex, Gemini CLI, Aider, …), and local model servers (Ollama). For each one it shows what it is doing, how much CPU and memory it holds, and how the machine is doing overall.

 TOPAGENTS · stephanos-mbp                        3 agents · 2 busy · 2 subagents · 17:20
 CPU ███░░░░░░░░░░░░  18%  8 cores · load 1.4   MEM ██████░░░░░░░░░ 6.0/16.0 GB   agents 10.8 GB
──────────────────────────────────────────────────────────────────────────────────────────
 ● BUSY   Claude Code · southflorals-platform-17   2 subagents · cpu 42% · 5.5 GB · up 1d17h
           ~/work/southflorals-platform · feat/sou-12110-clock-in-requires-shift
   asked   make sure only can clockin with a shift from the scheduler                 3m ago
   doing   Bash · Run the unit tests                                                 12s ago
   memory  ███░░░░░░░ 34% of RAM · self 512 MB · next ×2 2.7 GB · vitest ×4 1.1 GB · tsc 922 MB · +1 more
   agents  ▶ Explore · Map the delivered cron · Grep · deliveredAt                       12s
           ⏸ general-purpose · Fix the flaky test · Bash · pnpm test               quiet 14m
           ✓ Plan · Plan the Reviews tab                                         done 4m ago
──────────────────────────────────────────────────────────────────────────────────────────
 ◆ RUN    Codex                                                     cpu 0% · 310 MB · up 22m
           ~/code/other-project · main
   memory  ░░░░░░░░░░ 2% of RAM · self 290 MB · node 20 MB
──────────────────────────────────────────────────────────────────────────────────────────
 ● BUSY   Ollama · ollama serve                                    cpu 0% · 5.0 GB · up 3h00m
   models  llama3.1:8b 5.0 GB · 100% GPU                                       unloads in 4m
   memory  ███░░░░░░░ 31% of RAM · self 120 MB · ollama 4.9 GB

 [q] quit  [↑/↓] scroll

Quick start

You need Go 1.23 or newer (brew install go on macOS, or https://go.dev/dl on Linux).

git clone https://github.com/Stephnn0/topagents.git
cd topagents
make build          # builds bin/topagents
./bin/topagents     # live screen: q quits, ↑/↓ scroll

To have it on your PATH:

go install github.com/Stephnn0/topagents/cmd/topagents@latest
topagents

Works on macOS (Apple Silicon and Intel) and Linux. Windows is not supported.

Usage

topagents                 # live, redrawn every 2 s
topagents --once          # one plain snapshot, fits the terminal width
topagents --json          # one snapshot as JSON, for scripts
topagents --interval 5s   # slower refresh
topagents --no-color      # NO_COLOR is honoured too
topagents --version

Reading the screen

• Header, line 1: how many agents, how many are busy, how many subagents are active, the clock.
• Header, line 2: the machine. CPU across all cores with core count and load, RAM used of total, and how much of that RAM the agents hold between them. Bars go green, yellow, red at 60 % and 85 %.
• One block per agent: ● BUSY is working on a request now, ○ IDLE is waiting for its user, ◆ RUN is alive but says no more. The right side has the CPU of its whole process tree (measured between two refreshes, like top), its total memory, and uptime.
• asked / doing: the last prompt typed into the session and the tool it is running right now (last on an idle session).
• memory: the session's share of RAM, then its own process and its heaviest children grouped by name. This is the line to watch on a small machine.
• agents: one line per subagent. ▶ running with its current tool, ⏸ quiet has written nothing for 10 minutes, ✓ done finished (shown for 10 minutes). Subagents run inside the session's process, so they have no memory figure of their own.

What it reads

Read-only and local-only. It runs ps once per refresh and reads the files each agent already writes. Nothing leaves the machine, nothing is written to any agent's directory, and no process is ever signalled.

Agent	Detail
Claude Code	sessions, last prompt, current tool, subagents, CPU, memory
Ollama	loaded models, size, % on GPU, when they unload
Codex, Gemini CLI, Aider, Cursor Agent, opencode, Goose, llama.cpp	process, folder, branch, uptime, CPU, memory

An agent running inside another agent's process tree (Claude Code running codex as a tool) is not listed separately; its cost is in its parent's total.

Adding an agent: write an adapter in internal/adapters/<name>/ that implements agent.Adapter, register it in cmd/topagents/main.go before generic, and test it against a fixture captured from a real install.

Development

make test    # go test ./...
make vet
make once    # build and print one snapshot

Releases are built by GoReleaser from a v* tag: Homebrew tap for macOS, .deb and .rpm for Linux. See .goreleaser.yaml.

License

MIT