agent-tui

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