agentop

like htop, but for AI coding agents

A terminal UI for monitoring AI coding agents in real time. Inspect running sessions, track token usage, watch costs accumulate, and see what every agent on your machine is doing — without leaving the terminal.

---

Supported agents

Agent	Status	Config path
Claude Code	Supported	~/.claude/
Codex	Supported	~/.codex/
Antigravity	Supported	~/.antigravity/
OpenCode	Supported	~/.opencode/

---

What you see

agentop presents a multi-panel TUI. Each panel updates live as agents write to their session files.

Process monitor CPU usage, memory footprint, and uptime for every active agent process. Modelled after htop's process list — sortable by any column.

Usage stats Token counts (prompt and completion), estimated cost, and session count per agent. Aggregates across all running and recently completed sessions.

Quota tracking Remaining API budget against configured limits. Raises a visual alert when an agent is close to exhausting its allocation.

Timeline view A scrollable chronological log of agent events — session starts, tool calls, errors, and completions — across all monitored agents in a single stream.

---

Data flow

~/.claude/ + ~/.codex/ + ~/.antigravity/ + ~/.opencode/
        |
        v
   agentop (file watchers + process scan)
        |
        v
   TUI Dashboard

agentop reads only local files and process metadata. No network calls are made to any AI provider.

---

Installation

pip install agentop

Python 3.9 or later is required. No additional system dependencies.

From source

git clone https://github.com/dadwadw233/agentop.git
cd agentop
pip install -e .

---

Usage

# Launch the TUI
agentop

# Monitor a specific agent only
agentop --agent claude

# Set a refresh interval in seconds (default: 1)
agentop --interval 2

# Print a one-shot summary to stdout and exit
agentop --snapshot

Keyboard shortcuts inside the TUI:

Key	Action
q	Quit
Tab	Switch panel
j / k	Scroll down / up
s	Cycle sort column
r	Force refresh
?	Show help overlay

---

Data sources

agentop derives its information from the following sources:

• Session files — JSON or JSONL files written by each agent under its config directory. The schema differs per agent; agentop ships a normalisation layer for each supported format.
• Process table — /proc on Linux, ps on macOS. Used to correlate session files with live PIDs and measure CPU/memory.
• Cost estimation — Token counts from session files multiplied by per-model pricing bundled with agentop. Prices are updated on each release and can be overridden in ~/.config/agentop/pricing.toml.

---

Configuration

agentop looks for a config file at ~/.config/agentop/config.toml. All fields are optional.

[display]
interval   = 1        # refresh rate in seconds
theme      = "dark"   # "dark" or "light"

[quota]
daily_usd  = 20.0     # alert threshold in USD

[agents]
# Disable an agent by setting enabled = false
[agents.codex]
enabled = false

---

Known limitations

• Windows is not supported. The process monitor relies on POSIX interfaces. WSL2 works.
• Session file formats change without notice. Agent vendors do not publish stable schemas. agentop may lag behind a new release by a few days until the parser is updated.
• Cost figures are estimates. Pricing tables are maintained manually. Batch discounts, enterprise agreements, and cached-prompt pricing may not be reflected accurately.
• Multi-user machines. agentop only reads the current user's home directory. Agents running under other users are not visible.
• Very high session volumes. If a session directory contains tens of thousands of files, the initial parse can take several seconds.

---

Roadmap

• Persistent session history database (SQLite)
• Export to CSV / JSON
• Configurable cost alerts via desktop notification
• Windows support via a cross-platform process backend
• Plugin API for community-contributed agent parsers
• Web dashboard mode (read-only HTTP server, no extra dependencies)

---

Changelog

0.3.0

• Added OpenCode support
• Timeline view panel
• --snapshot flag for non-interactive output

0.2.0

• Antigravity support
• Quota tracking panel
• pricing.toml override for custom cost tables

0.1.0

• Initial release
• Claude Code and Codex support
• Process monitor and usage stats panels

---

Contributing

Bug reports and pull requests are welcome. Please open an issue before starting substantial work so we can agree on direction.

# Run tests
pytest

# Run the linter
ruff check .

---

License

MIT. See LICENSE for the full text.