AgentSkillsCN

agent-tui

利用 agent-tui 自动化终端 UI（TUI）应用，用于测试、检查、演示以及脚本化交互。适用于自动化 CLI/TUI 流程、对终端应用进行回归测试、验证交互行为，或从终端 UI 中提取结构化文本时使用。此外，当用户询问 agent-tui 是什么、如何运作，或希望进行演示时，也可使用此功能。切勿用于网页浏览器、GUI 应用，或非终端界面。

SKILL.md
--- frontmatter
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