stevengonsalvez/agents-in-a-box · Pull Request #240

abtop (top-for-agents): native-key TUI embed + `ainb abtop` CLI

Steven Gonsalvez

branch feat/abtop · 5 commits

feat/abtop → main

+2462 / −6 27 files

What this PR does

Integrates the external abtop TUI ("htop for AI coding agents") into ainb-tui exactly the way the existing witr plugin is integrated — a discoverable plugin crate plus a hardcoded host embed that hands the terminal to the real abtop binary full-screen, so every abtop key works natively (it is the real binary).
Adds a sidebar item "abtop" / top-for-agents (📡, shortcut t) and a global t home hotkey. Selecting it suspends ainb and attaches abtop --exit-on-jump in a dedicated tmux session, resuming ainb on quit.
Adds an ainb abtop CLI that shells abtop --once (extra args forwarded verbatim, stdio inherited for a real TTY); a missing binary prints a platform-aware install hint and exits non-zero.
Offers abtop --setup (the Claude rate-limit StatusLine hook) once on first launch via a consent dialog — ainb never writes ~/.claude without an explicit "Enable".

The journey, recorded

ainb home → t → rate-limit setup consent → "Just open abtop" → real abtop monitor full-screen → q returns. Recorded with vhs driving the real ainb + abtop binaries.

Frame-truth verification

Not "the screen shows something" — each frame was extracted and read to assert the exact user-visible outcome.

ainb home with abtop sidebar item and the rate-limit consent dialog — Sidebar carries `📡 abtop [t]`; first launch raises the **"Enable abtop rate-limit tracking?"** consent — `[ Enable ] [ Just open abtop ] [ Don't ask again ]`.

real abtop monitor rendered full-screen inside the ainb embed — The real **abtop v0.4.7** monitor, full-screen inside the embed — quota / tokens / projects / ports / mcp / sessions panels with live agent rows. Native keys, no re-implementation.

How it works — two paths (the witr pattern)

PATH A — plugin crate `ainb-plugin-abtop` (discoverable)
  detect (which abtop?) · install-hint empty-state · `abtop --once` CLI seam
  no data-render: abtop has no JSON / no lib crate

PATH B — host embed in ainb-core (the live menu UX)
  press `t` / select sidebar
        │
        ▼
  AppEvent::GoToAbtop ──▶ first launch? ──▶ consent: run `abtop --setup`?
        │                                          │ Enable / Just open / Dismiss
        ▼                                          ▼
  AsyncAction::AttachAbtop
        │
        ▼
  tmux new-session -A -d -s ainb-abtop "abtop --exit-on-jump" + attach
  ainb SUSPENDS ──▶ real abtop full-screen ──▶ quit ──▶ ainb resumes

abtop has no machine-readable mode, so re-rendering its data inside ainb isn't possible — the full-screen attach is the only way to get native keys, and it's what witr does too.

Verification

tripwire_abtop.rs — green (tmux e2e J6→J1) ainb-plugin-abtop — 42 tests host — 896 lib tests ainb abtop absent → hint + exit 1 CLI count test 23 → 24 stable rustfmt clean 9 docker tests — no daemon (environmental)

passing pre-existing / environmental

Locked decisions

Full-screen tmux attach (not in-pane) — the witr mechanism; gives 100% native keys.
ainb abtop = abtop --once — abtop has no JSON mode; thin scriptable alias.
Present/absent version gate — abtop is a churning fork; no brittle min-version parse.
Platform-aware install hint → canonical graykode/abtop — its releases carry the installer asset and graykode/tap carries the brew formula; the fork has no release assets.
abtop --exit-on-jump — Enter jumps to an agent's pane and quits abtop, returning control cleanly.
abtop --setup offered on first launch via consent — never silently touches ~/.claude/settings.json.

Code-review findings (no blockers — both fixed)

Canonical install hints — the installer URL pointed at the fork (no release assets there); repointed all four hint sites at graykode/abtop so the commands are paste-ready.
Setup-session reuse — the abtop --setup tmux session now uses -A (attach-or-create), so a stale/slow setup pane can't fail a retry with a misleading "is abtop installed?" error.

Files

ainb-plugin-abtop/ (new crate · 16 files) ainb-core/app/{events,state}.rs ainb-core/main.rs (tmux attach) ainb-core/cli/registry.rs (AbtopCommand) components/sidebar.rs · screens/{mod,builtin}.rs tests/tripwire_abtop.rs Cargo.toml · scripts/build-plugins.sh