pproenca/agent-tui

Overview

This skill drives terminal UI (TUI) applications programmatically for testing, automation, and inspection. It lets you run a TUI under control, observe the screen, interact with elements or send keystrokes, and verify outcomes. Use it to automate CLI workflows, build reliable regression tests for terminal apps, or extract structured data from interactive terminals.

How this skill works

The skill interacts with the TUI via a repeating observe-decide-act loop: take a fresh screenshot (the character grid), locate elements or text, perform actions (click, input, press keys), then wait and verify the result. Because terminal screens are redrawn constantly, every action must be followed by a new snapshot and stability/assert checks to avoid flaky automation. Sessions are launched, managed, and cleaned up via the CLI commands.

When to use it

• Automating interactive CLI or TUI workflows (forms, menus, wizards).
• Regression testing of terminal applications that lack a stable API.
• Verifying visual or text-based outcomes in an interactive session.
• Extracting structured data from complex terminal screens.
• Demonstrating agent-tui capabilities or running a live demo (e.g., running top).

Best practices

• Always re-snapshot after every action — element refs become invalid after any UI change.
• Never act while the UI is animating; use wait --stable before interacting.
• Verify outcomes explicitly with wait "expected text" --assert rather than assuming success.
• Clean up sessions with agent-tui kill to avoid orphaned processes.
• Prefer element refs from screenshot -e --json for unambiguous targeting; fall back to text matches only when needed.

Example use cases

• Run a TUI installer, navigate prompts, fill inputs, and assert success messages for CI regression tests.
• Automate navigation of a curses-based dashboard to extract table data as JSON.
• Simulate user keystrokes to reproduce and diagnose flaky interactions in an interactive CLI tool.
• Provide a live demo of an app by running it under control and streaming the terminal to an observer.