Saucebox Registry
← Browse

@napisani/agent-tui

A

Automate terminal UI (TUI) apps with agent-tui for testing, inspection, demos, and scripted interactions. Use when automating CLI/TUI flows, regression testing terminal apps, verifying interactive behavior, or extracting structured text from terminal UIs. Also use when asked what agent-tui is, how it works, or to demo it. Do not use for web browsers, GUI apps, or non-terminal interfaces.

skillclaude

Install

agr install @napisani/agent-tui --target claude

Writes 1 file into .claude/skills/, pinned to git-d05c5c78.

  • .claude/skills/agent-tui/SKILL.md

Document

name: agent-tui description: > Automate terminal UI (TUI) apps with agent-tui for testing, inspection, demos, and scripted interactions. Use when automating CLI/TUI flows, regression testing terminal apps, verifying interactive behavior, or extracting structured text from terminal UIs. Also use when asked what agent-tui is, how it works, or to demo it. Do not use for web browsers, GUI apps, or non-terminal interfaces.

agent-tui

Quick start

  • Verify install: agent-tui --version
  • Install with npm i -g agent-tui (or pnpm add -g agent-tui, bun add -g agent-tui).
  • Alternate install: curl -fsSL https://raw.githubusercontent.com/pproenca/agent-tui/master/install.sh -o /tmp/agent-tui-install.sh && sh /tmp/agent-tui-install.sh or cargo install --git https://github.com/pproenca/agent-tui.git --path cli/crates/agent-tui.
  • If you used the install script, ensure ~/.local/bin is on your PATH.
  • Start a session: agent-tui run --format json <command> -- <args...>
  • Observe: agent-tui screenshot --format json
  • Act: agent-tui press Enter or agent-tui type "text"
  • Wait or verify: agent-tui wait "Expected text" --assert or agent-tui wait --stable
  • Cleanup: agent-tui kill

Core workflow

  1. Run the app with agent-tui run and capture session_id from JSON output.
  2. Take a fresh snapshot with agent-tui screenshot or agent-tui screenshot --format json.
  3. Decide the next action based on the latest snapshot.
  4. Act with press or type.
  5. Synchronize with wait --assert or wait --stable.
  6. Repeat from step 2 until the task finishes.
  7. Clean up with agent-tui kill.

Reliability rules

  • Re-snapshot after every action that could change the UI.
  • Never act on a changing screen; wait for stability first.
  • Verify outcomes with wait --assert instead of assuming success.
  • Always end runs with kill or sessions cleanup.

Session handling

  • Use --session <id> for every command if more than one session exists.
  • If you lose the session id, run agent-tui sessions and agent-tui sessions show <id>.

Live preview (optional)

  • Ask whether a live preview is desired.
  • Start preview: agent-tui live start --open
  • Stop preview when done: agent-tui live stop

Deep-dive references

  • Full CLI coverage and options: references/command-atlas.md
  • JSON output contract: references/output-contract.md
  • End-to-end command sequences: references/flows.md
  • Quick command selection: references/decision-tree.md
  • Session lifecycle and concurrency: references/session-lifecycle.md
  • Assertions and test oracles: references/assertions.md
  • Failure recovery playbook: references/recovery.md
  • Safety and confirmation prompts: references/safety.md
  • Clarification checklist: references/clarifications.md
  • Test plan template: references/test-plan.md
  • Demo script: references/demo.md
  • User prompt templates: references/prompt-templates.md
  • Minimal command sets by use case: references/use-cases.md
  • Explorer/replay automation skill: ../tui-explorer/SKILL.md

Trustgrade A

  • passBody integrity

    Whether the stored document is plausibly the kind of file the artifact declares, rather than something fetched by mistake.

  • passType matchnot applicable to this artifact type

    Whether the artifact is really the kind of thing its metadata claims it is.

  • passFreshness

    How long since the source repository was last pushed to.

  • passPrompt injection

    Scans the artifact's own text for instructions aimed at your agent rather than at you.

  • passLicense

    Whether the source repository declares an SPDX license permissive enough to redistribute.

How the grade is calculated

Each check contributes 0 points when it passes, 1 when it warns, and 2 when it fails. The total maps to a letter:

  • Aevery check passed
  • Bone warning
  • Ctwo warnings
  • Dprompt injection or body integrity failed, or three warnings
  • Fone of those failed, and something else is wrong

These are automated hygiene checks, not a security audit, and not a dependency or vulnerability scan. A grade of A means nothing was flagged — not that the artifact is safe.

Versions

  • git-d05c5c78b94b2026-07-31