AGTOP(1)

NAME
agtop - terminal UI for monitoring AI coding agents

SYNOPSIS
agtop [OPTIONS]

DESCRIPTION
agtop is a top-like process monitor specialised for AI coding agents. It detects Claude Code, OpenAI Codex, Block Goose, Aider, Google Gemini, Cursor, Continue, Opencode, Copilot CLI, and other agent CLIs out of the box, and reads each one's session transcript on disk to enrich its row with the current tool, model, in-flight subagents, cumulative token usage, estimated dollar cost, context-window fill, and loaded skills / plugins.

OPTIONS

-1, --once
    Print a one-shot snapshot and exit (no TUI).

-j, --json
    Emit a machine-readable JSON snapshot; implies --once.

-i SECONDS, --interval=SECONDS
    TUI / iteration refresh interval (default 1.5).

-n COUNT, --iterations=COUNT
    With --once, print N snapshots delimited by ``---''.

-f SUBSTR, --filter=SUBSTR
    Only show agents whose label / cmdline / cwd / project / pid contains SUBSTR.

-s KEY, --sort=KEY
    One of smart, cpu, mem, tokens, uptime, agent. Default smart.

-m LABEL=REGEX, --match=LABEL=REGEX
    Add a custom agent matcher. Repeatable.

--no-color
    Disable ANSI colors in --once / --json output.

--theme=NAME
    TUI palette: one of default, dracula, nord, gruvbox, monochrome.

--top=N
    With --once, only show top N agents (0 = all).

--list-builtins
    Print the built-in matcher list and exit.

--prices=PATH
    TOML file overriding / extending the bundled model price table.

--watch
    One summary line per tick to stdout; pipes cleanly.

--threshold-cpu=PERCENT
    In --watch, exit 3 if aggregate CPU% exceeds N.

--threshold-tokens-rate=TOK_PER_MIN
    In --watch, exit 4 if average tokens/min exceeds N.

--pid=PID
    Open the TUI focused on a specific PID with the detail popup already showing.

-V, --version
    Print version and exit.

-h, --help
    Print full help and exit.

ENVIRONMENT

AGTOP_MATCH
    Semicolon-separated `LABEL=REGEX' matchers (additive to built-ins). Equivalent to repeating -m.

AGTOP_PRICES
    Path to a TOML price-table override file (equivalent to --prices).

NO_COLOR
    When set, disables ANSI colors in --once / --json output.

FILES

~/.claude/projects/<encoded-cwd>/<session>.jsonl
    Claude Code session transcripts.

~/.codex/sessions/<YYYY>/<MM>/<DD>/<rollout>.jsonl
    OpenAI Codex rollout transcripts.

~/.config/goose/sessions/
    Block Goose session transcripts.

<cwd>/.aider.chat.history.md
    Aider chat history.

~/.gemini/sessions/<id>.json
    Google Gemini session transcripts.

~/.claude/skills/<name>/SKILL.md
    — <cwd>/.claude/skills/<name>/SKILL.md Claude Code skill manifests (user-global + project-local).

~/.claude/plugins/installed_plugins.json
    — ~/.claude/settings.json Claude Code plugin marketplace + per-user enabled-plugin map.

EXIT STATUS

0   Successful exit.

2   Argument parse error or runtime error.

3   --watch''--threshold-cpu' exceeded.

4   --watch''--threshold-tokens-rate' exceeded.

SEE ALSO
top(1), htop(1), btop(1), ps(1).

AUTHOR
Matt Brassey <matt@brassey.io>