Dogfooding TUIs with agent-tty

Use this skill when the user wants structured exploratory testing, bug hunting, release-readiness validation, or UX review for a terminal application or TUI.

Prerequisites

This workflow assumes the agent-tty core skill is already loaded. If it is not, load it first with agent-tty skills get agent-tty. Use this skill as the specialized QA layer on top of the core terminal automation workflow.

Dogfooding Workflow

1. Create an isolated home so artifacts and session state stay reviewable and do not pollute the real user environment.
2. Check renderer and browser prerequisites with doctor --json before any screenshot or recording work.
3. Create the session with a known shell or launcher command and capture the returned session ID.
4. Launch the target app intentionally:
   • Use run for fast setup commands or scripted launches.
   • Use type for literal keystroke-by-keystroke text entry that should appear in the session.
   • Use send-keys for control input such as arrows, Enter, Escape, Ctrl+C, or function-key navigation.
5. Wait on observable state with wait instead of blind sleeps:
   • --text when a label, prompt, or status message should appear.
   • --screen-stable-ms when the UI is animating or repainting.
   • --idle-ms when command completion matters more than screen text.
6. Capture the current screen state with snapshot --format text --json for searchable text evidence.
7. Capture visual proof with screenshot --json whenever layout, color, cursor, or rendering quality matters.
8. Export motion proof with record export --format webm --json when the issue involves navigation, animation, resize behavior, focus handling, or transient corruption.
9. Repeat the loop for every meaningful scenario: startup, first-run prompts, resize, help flows, error handling, and teardown.
10. Destroy the session when the investigation is complete.

Recommended Session Skeleton

DOGFOOD_HOME="$(mktemp -d)"
agent-tty --home "$DOGFOOD_HOME" doctor --json
SESSION_ID=$(agent-tty --home "$DOGFOOD_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
agent-tty --home "$DOGFOOD_HOME" run "$SESSION_ID" '<launch-command>' --no-wait --json
agent-tty --home "$DOGFOOD_HOME" wait "$SESSION_ID" --screen-stable-ms 1000 --json
agent-tty --home "$DOGFOOD_HOME" snapshot "$SESSION_ID" --format text --json
agent-tty --home "$DOGFOOD_HOME" screenshot "$SESSION_ID" --json
agent-tty --home "$DOGFOOD_HOME" record export "$SESSION_ID" --format webm --json
agent-tty --home "$DOGFOOD_HOME" destroy "$SESSION_ID" --json

Evidence Checklist

Collect enough evidence that another reviewer can reproduce the result without guessing:

• Exact repro commands, including the launch command and every subsequent run, type, or send-keys action.
• Terminal dimensions used for the repro, especially if layout or wrapping is part of the issue.
• At least one screenshot path for the failing or noteworthy state.
• A WebM export path when motion, navigation sequence, or transient rendering matters.
• Snapshot text for the most relevant terminal states so reviewers can search output quickly.
• Expected behavior versus actual behavior written in plain language.
• Whether the issue reproduces consistently, intermittently, or only after a specific setup sequence.
• Cleanup notes, especially if the app leaves background state, temp files, or a broken terminal mode behind.

Issue Taxonomy

Use consistent labels and notes so findings can be triaged quickly:

• Rendering corruption — garbled characters, color loss, double paint, cursor artifacts, or stale cells.
• Resize/layout — wrapping bugs, clipped panes, overlapping widgets, incorrect recompute after resize, or unusable small-screen behavior.
• Focus/input — lost keystrokes, wrong focused widget, modal traps, broken shortcuts, or incorrect key interpretation.
• Scrollback — missing history, jumpy scrolling, incorrect paging, or broken mouse wheel behavior.
• Alt-screen — failure to enter or exit cleanly, leaked UI frames, or shell prompt corruption after exit.
• Copy/paste — paste corruption, bracketed-paste issues, selection problems, or unsafe multiline submission behavior.
• Performance/startup — slow launch, delayed first paint, high-latency navigation, or visible stutter.
• Crash/recovery/state loss — panic, unexpected exit, broken resume path, lost form state, or inconsistent restoration after restart.

Report Template

Use this structure when handing findings back to the user or a maintainer:

• Title: concise issue summary
• Environment: OS, shell, app version/commit, terminal dimensions, and whether doctor --json passed
• Reproduction steps: numbered sequence with the exact agent-tty commands and key inputs used
• Evidence bundle: paths to snapshot text, screenshot PNG, WebM, and any additional logs
• Expected behavior: what should have happened
• Actual behavior: what happened instead
• Impact: severity, user-facing risk, and whether it blocks release-readiness
• Workaround: any known mitigation or safer path
• Regression suspicion: whether this looks new, long-standing, or tied to a recent change

Prefer concise, repeatable repros and artifact-backed findings over narrative descriptions. The goal is a reviewable proof bundle, not just an anecdote.