donaldfilimon/abi / .agents/skills/run-tui
run-tui
VerifiedBuild the abi CLI and drive the interactive diagnostics dashboard (`abi dashboard` / `abi tui` / `abi --tui`) through a tmux pty — launch it, screenshot/capture the rendered pane, assert it painted, send the quit key, tear down. Use to run, launch, screenshot, or smoke-test the abi TUI/dashboard headlessly. The one abi surface that needs a real terminal.
SKILL.md
View on GitHub---
name: run-tui
description: Build the abi CLI and drive the interactive diagnostics dashboard (`abi dashboard` / `abi tui` / `abi --tui`) through a tmux pty — launch it, screenshot/capture the rendered pane, assert it painted, send the quit key, tear down. Use to run, launch, screenshot, or smoke-test the abi TUI/dashboard headlessly. The one abi surface that needs a real terminal.
---
# run-tui — drive abi's interactive diagnostics dashboard
Driver: **`.agents/skills/run-tui/tui.sh`** (paths relative to repo root).
`abi dashboard`/`tui`/`--tui` are interactive on a real TTY; this driver gives
them a **tmux pty**, captures the rendered pane, asserts the dashboard painted,
sends `q`, and kills the session. Evidence is the `RESULT:` line. Fully local.
## Prerequisites
- **`tmux`** (`brew install tmux`). The driver checks for it and fails fast if absent.
## Run (agent path)
```bash
.agents/skills/run-tui/tui.sh # drives `abi dashboard` (default)
.agents/skills/run-tui/tui.sh tui # drive `abi tui` instead
```
Launches the command under `tmux new-session` (200x50 pane), waits for paint,
captures the pane, and asserts the `ABI Diagnostics Dashboard` marker is present
and there's **no** `errno 19`/`tcgetattr`/panic. Sends `q` (the quit key —
`isQuitKey` accepts `q`/`Q`/Esc) and confirms the session tore down. Prints
`RESULT: PASS` (exit 0) or a FAIL count.
To eyeball it yourself: `tmux capture-pane -pt <session>` shows the System pane
(GPU backend, accelerated, native-linked) and the Plugins pane (16 registered).
Historical verification: **PASS** on stable Rust via `./tools/cargo.sh` —
dashboard box + System + Plugins panes render under the pty; `q` quits; session
cleaned up.
## Gotchas (battle scars)
- ⚠️ **Always build with `./tools/cargo.sh`** (never bare Homebrew `cargo`).
The driver needs `tmux` on PATH (`brew install tmux`); do not let brew's
stable cargo shadow the repository-selected toolchain used for the build.
- **A pty is mandatory for the interactive path.** Piped stdin or `/dev/null`
intentionally uses the one-shot fallback; use tmux when you need to prove the
live loop paints and accepts `q`.
- **Give it time to paint.** The driver sleeps 2.5s before capture; a busy
machine may need more. A blank pane = captured too early, not a failure to run.
- `Accelerated: yes` / `Native Linked: yes` in the System pane is the dashboard's
own rendering of backend state; the CLI `backends` report phrases the same
Metal-linked/CPU-fallback status differently — both are correct.
- For the render loop and screen lifecycle internals, use the
`tui-navigation-guide` subagent.
## Troubleshooting
| Symptom | Fix |
|---|---|
| `tmux not installed` | `brew install tmux`. |
| `build` FAIL | Use `./tools/cargo.sh build -p abi-cli`, then `./tools/check.sh`. |
| `dashboard did not paint` | Increase the `sleep`, or confirm the pane size (`-x/-y`) is large enough. |
| `tty error / panic in pane` | Regression in the interactive terminal path; confirm launch went through `tmux new-session`. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |