Supported agents

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:

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.