agentop

A terminal UI (TUI) process inspector for macOS and Linux that monitors running Claude Code and OpenAI Codex CLI processes. Displays an expandable process tree with live CPU, memory, status, and uptime metrics, and lets you drill into any process for sparkline charts and full command-line details.

Screenshot

The tree view lists every detected Claude / Codex root process in orange (Claude) or green (Codex), with their child processes indented in grey. Pressing Enter opens a detail view for the selected process, showing CPU%, memory, full command line, and live sparkline charts over the last 30 samples. Columns are sortable by pressing Tab to cycle through them.

Features

• Cross-platform — works on macOS and Linux.
• Automatic detection of Claude Code and OpenAI Codex CLI processes using multiple heuristics (process name, argv[0], exe path).
• Process tree built from OS parent-PID relationships, with expand/collapse support that persists across refresh cycles.
• Sortable columns — sort by PID, name, CPU%, memory, status, or uptime in ascending or descending order.
• Live refresh every 2 seconds on a background blocking thread, so the async UI reactor is never stalled.
• Detail view with per-process info table (CPU%, memory, exe path, working directory, environment variable count) and rolling sparkline charts for CPU and memory history.
• Context-sensitive footer showing only the key bindings relevant to the active view.
• Safe terminal restoration on both clean exit and panic.

Installation

Requires Rust 1.70 or later.

Install from crates.io (recommended)

cargo install agentop

Install from GitHub

cargo install --git https://github.com/leboiko/agentop.git

Install from a local clone

git clone https://github.com/leboiko/agentop.git
cd agentop
cargo install --path .

cargo install builds with --release by default, so the binary is fully optimized (LTO, single codegen unit, stripped symbols) as configured in the [profile.release] section of Cargo.toml.

Verify installation

agentop --version   # or just: which agentop

If ~/.cargo/bin is not on your PATH, add it:

# bash/zsh
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Uninstall

cargo uninstall agentop

Usage

agentop

The application opens in an alternate screen buffer (your terminal history is not disturbed) and begins scanning immediately.

Keybindings

Tree view

Detail view

Process Detection

Detection logic is implemented in src/process/filter.rs and operates on a snapshot of every process's name, argv, and exe path.

Claude Code

A process is classified as Claude if any of the following conditions hold:

1. process.name == "claude"
2. argv[0] == "claude" — catches cases where sysinfo reports the underlying engine name (e.g. "node") instead of the display title.
3. The exe path contains .local/share/claude — covers the typical installation directory on Linux/macOS.
4. The process name consists entirely of digits and dots (a version string such as "1.2.3") and the exe path contains "claude/versions" — matches versioned Electron bundles shipped by the installer.

OpenAI Codex CLI

A process is classified as Codex if any of the following conditions hold:

1. process.name == "codex"
2. argv[0] == "codex"
3. Any argv token contains "@openai/codex" or "codex.js" — catches npx-launched invocations where the process name is "node".

All child processes (those whose parent PID matches a detected root) are included in the tree regardless of their own name.

Architecture

src/
  main.rs          Entry point; tokio runtime setup, event loop, scanner
                   channel wiring, and frame rendering dispatch.
  app.rs           Central application state (App) and all state mutations.
                   Translates Actions into state changes, manages history
                   ring buffers, and drives flat-list rebuilds.
  action.rs        Enum of all discrete user actions (Quit, MoveUp, ...).
  event.rs         Async EventHandler that multiplexes crossterm key events,
                   periodic Tick signals, and Render signals over a single
                   channel.
  tui.rs           Terminal initialisation / restoration helpers and the
                   panic hook that ensures raw mode is always cleaned up.
  process/
    info.rs        ProcessInfo struct: owned snapshot of one OS process.
    filter.rs      is_claude_process / is_codex_process predicates.
    scanner.rs     ProcessScanner wrapping sysinfo::System; incremental
                   refresh with CPU delta seeding.
    tree.rs        Forest construction from flat snapshots, flatten_visible,
                   and expand/collapse state helpers.
    mod.rs         Public re-exports.
  ui/
    tree_view.rs   Renders the scrollable Table with box-drawing tree
                   connectors, colour-coded rows, and a scrollbar.
    detail_view.rs Renders the detail panel: header, info table, CPU
                   sparkline, memory sparkline, and full command line.
    footer.rs      Context-sensitive one-line key-binding hint bar.
    format.rs      Shared formatting helpers (memory, duration).
    styles.rs      Shared Style / Color constants.
    mod.rs         Public re-exports.

The event loop runs at two independent rates: a tick rate of 2 seconds triggers a background scan, and a render rate of ~30 fps drives redraws. The scanner runs on a dedicated tokio::task::spawn_blocking thread to avoid blocking the async reactor during sysinfo syscalls.

Tech Stack

License

MIT