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