abtop: a terminal monitor for Claude Code, Codex CLI and OpenCode sessions

What abtop actually watches, and who needs it

The README frames abtop as btop for AI coding agents. The concrete problem it targets is visibility: when three or more agents run across different projects, there is no single place that shows which session is burning tokens, which one is close to filling its context window, and which one left a server listening on a port. abtop collects that into one TUI screen. The stated audience is developers who run Claude Code, Codex CLI or OpenCode concurrently, and who have hit a rate limit without noticing the quota draining. It is not a proxy and not a wrapper: according to the README, everything is read-only, with no API keys and no auth. That design decision is the most important thing about it. abtop never sits between your agent and its provider, so it cannot break a session by being wrong. It also means it can only report what local state already records.

How abtop discovers sessions from local process and file state

Sessions are discovered from local process and file state rather than from a network API, which is why multiple active profiles work across macOS, Linux and Windows. Claude Code configuration is resolved automatically from the platform config location, for example %USERPROFILE%\.claude on Windows, and abtop also auto-discovers ~/.claude and ~/.claude-* roots that contain both a sessions/ and a projects/ directory. OpenCode is different: abtop reads the local SQLite database at ~/.local/share/opencode/opencode.db, with %LOCALAPPDATA%\opencode and %APPDATA%\opencode probed as fallbacks on Windows, and it requires the sqlite3 binary in PATH. Per-platform dependencies in Cargo.toml reflect this split: proc_pidinfo on Apple targets, sysinfo on Windows, libc on Linux. Windows has no load average, so the README states LOAD is reported as 0 there. The supported-agent table is honest about the gaps: OpenCode has no context window percentage, no current task and no rate limit row, and subagents and memory status are Claude Code only.

Installing abtop and taking a first snapshot

On macOS and Linux the README gives a release installer script. It downloads the latest release binary and installs it; the Linux note adds that sqlite3 must be installed for OpenCode monitoring to work.

Installing abtop and taking a first snapshot (commands)

The installer is the shortest path:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/graykode/abtop/releases/latest/download/abtop-installer.sh | sh

If you prefer to build it, the crate is on crates.io and Cargo.toml sets rust-version to 1.88:

cargo install abtop

On Windows the README offers a PowerShell installer and notes that native support needs no WSL:

powershell -c "irm https://github.com/graykode/abtop/releases/latest/download/abtop-installer.ps1 | iex"

Before opening the TUI, a one-shot JSON snapshot is the fastest way to confirm that discovery is working. The README documents --once for a printed snapshot and --json for a single JSON snapshot intended for scripts and tools:

abtop --once
abtop --json

If that prints your sessions, the TUI will too. Launch it plainly, or with a theme and mouse capture:

abtop
abtop --theme dracula
abtop --mouse

The README recommends a terminal of 120x40 or larger, with 80x24 as the minimum; panels hide gracefully when the window is small. Mouse capture is off by default so terminal drag selection and copy keep working, which is a small but deliberate choice worth knowing before you wonder why clicks do nothing.

Configuration: hidden agents, extra Claude profiles, language

Settings live in ~/.config/abtop/config.toml. The README shows three keys beyond the theme. hidden_agents takes a case-insensitive list of agent CLIs to hide from the TUI, which is useful if you only use one agent. claude_config_dirs adds extra Claude Code profile roots to scan, on top of the auto-discovered ~/.claude and ~/.claude-* roots. language accepts en or zh, and when it is unset abtop auto-detects from LANG, switching to Simplified Chinese for any value starting with zh.

theme = "btop"
hidden_agents = ["codex"]
claude_config_dirs = ["~/.claude-personal", "~/.claude-work-team"]
language = "zh"

Theme choice is saved back to this file, so cycling with t at runtime persists. There are 12 built-in themes, four of them colorblind-friendly (high-contrast, protanopia, deuteranopia, tritanopia), plus light and white for bright terminals. The documentation does not describe a config schema version or a migration path, so treat the file as something abtop may rewrite.

The rate limit hook and terminal jump are the two features with real setup cost

abtop --setup installs a rate limit collection hook. That is the one operation in the README that writes something outside abtop's own config, and the README does not document what the hook installs, where it goes, or how to remove it. If you care about your Claude Code configuration staying untouched, read the source before running it. Terminal jump is the other feature with a dependency on your environment: pressing Enter focuses the terminal running the selected agent, and the README lists cmux, tmux and iTerm2 on macOS as supported. The tmux example is a session with abtop in one pane and two claude processes in others. If you use a terminal multiplexer outside that list, Enter will not take you anywhere. Killing is also available from the TUI: x kills the selected session and X kills all orphan ports. Given that abtop is otherwise read-only, those two keys are the exception, and they are worth knowing before you press them by accident.

Where abtop is the wrong tool

The limitations follow from the read-only, local-state design. There is no remote monitoring: abtop reads process and file state on the machine it runs on, so a container or a build box is invisible to it. OpenCode support is the weakest of the three agents; context window percentage, current task and rate limit are all marked unsupported, and discovery fails outright without sqlite3 in PATH, which the README warns about for Linux and Windows. On Windows the LOAD metric is always 0 because the platform has no load average, so any dashboard built around that number is misleading there. The README also does not document rollback for --setup, an uninstall procedure, or a way to export history; --json gives one snapshot and exits, which is enough for a script but not for a time series. If you need cost attribution across a team, or metrics from agents running on remote hosts, abtop is not the layer that solves it.

abtop versus htop, btop and plain log tailing

The obvious comparison is htop or btop, and the difference is the data source. Those tools read kernel process tables and report CPU, memory and threads; they will show you that a node process is using 400 MB, but not that a Claude Code session has consumed 80 percent of its context window. abtop reads agent-specific local state, which is why it can show token usage, context window percentage, rate limits, subagents and memory status, and why it cannot show you anything about processes that are not agents. Tailing log files is the other alternative, and it gives you raw detail abtop summarizes, at the cost of no aggregate view and no orphan port detection. The trade-off is scope for depth: abtop is narrower than a system monitor and shallower than raw logs, and it is useful precisely in the middle, when the question is which of my agents needs attention right now.

Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-09-10, so it is being worked on. Releases v0.5.1, v0.5.2 and v0.5.3 landed between 2026-06-29 and 2026-07-07, while Cargo.toml in the repository declares version 0.5.5, so the published release notes trail the source tree. Upgrades are cheap in the usual case: cargo install abtop replaces the binary, and the release installer script always fetches the latest release. The dependency list is short and mainstream (ratatui, crossterm, serde, chrono, dirs), which keeps build times and supply-chain surface small. The project is MIT licensed, which permits commercial use and modification; that is a statement about the licence text, not legal advice, and the usual obligation to keep the copyright notice applies. The one upgrade risk is the config file, since abtop writes the theme back to ~/.config/abtop/config.toml and the README does not describe a schema version.

Editorial conclusion

Adopt abtop if you regularly run several agent sessions in parallel and want a single read-only terminal view of tokens, context window percentage and orphan ports, and you are comfortable installing a binary from the release script or building from source with Rust 1.88 or newer. Skip it if you only ever run one agent, if you need metrics on a remote machine, or if you depend on OpenCode without a sqlite3 binary in PATH, because that discovery path simply does not work without it. Before rolling it out, verify the install path on your platform, confirm sqlite3 is present where OpenCode sessions matter, and check that the --setup rate limit hook writes what you expect. The README does not document uninstall or rollback, so plan that step yourself.

Frequently asked questions

Official sources

1. graykode/abtop on GitHub
2. Issues
3. License: MIT
4. README
5. Releases