tui-verify-change

name	tui-verify-change
description	Verify a change to Warp's headless TUI front-end (crates/warp_tui) by running it under tmux and reading the rendered screen back with `tmux capture-pane` — the agent sees the real frame, no computer_use required. Use whenever you change TUI UI, rendering, input, or behavior and need to confirm the real on-screen result.

tui-verify-change

Verify a change to Warp's headless TUI front-end (crates/warp_tui, and the cell-grid element library in crates/warpui_core/src/elements/tui) by running it and reading back the actual rendered screen.

The whole point: the TUI is a console program, so you can run it under tmux, drive it with tmux send-keys, and read the real rendered frame straight back with tmux capture-pane. You (the agent) see the actual screen text — no computer_use, no real display, no cloud screenshot agent, and no relying on a separate watcher's description of what it saw. (Contrast the GUI-only gui-onboarding-verification-skill, gui-integration-test, gui-integration-test-video, and the computer_use / verify-ui-change-in-cloud flow.) This is the fast, preferred way to confirm a TUI change end-to-end.

This skill covers the manual live-run verification. For a durable regression that runs in CI, also add a render-to-lines unit test per tui-testing — the two are complementary: the live run confirms real behavior; the snapshot test locks it in.

When to use

• You changed anything a TUI user sees or interacts with: an element/layout in crates/warpui_core/src/elements/tui, a TUI view/screen in crates/warp_tui (transcript, input, zero state, login placeholder, etc.), TUI keybindings, or TUI rendering/behavior.
• You want to confirm the actual rendered result, not just that it compiles or a unit test passes.

If your change is GUI-only (app/, WarpUI pixel Element/View), this is the wrong skill — use the GUI verification path instead.

Step 1 — Build the TUI

Always build with a small job count so the large warp dependency tree doesn't OOM the machine:

cd <warp-repo-root>
CARGO_BUILD_JOBS=2 cargo build -p warp_tui --bin warp-tui-oss

• warp-tui-oss is the OSS channel binary and the safest default (no internal warp-channel-config generator required). ./script/run-tui does the equivalent, selecting the internal local binary when the generator is available and falling back to warp-tui-oss otherwise.
• Fix all compile errors before running (see fix-errors). The first build of this tree takes a while; incremental rebuilds after a one-line change are fast (~10s), so the edit → rebuild → re-capture loop below is quick.

Logged-in vs logged-out (important)

The OSS build starts logged out and stops at a Sign in to continue placeholder (it drives a device-authorization login flow that needs a browser). The login-gated root has three pre-session states you may see:

• AwaitingLogin → a centered placeholder that reads Sign in to continue, then Opening your browser… (or, once the device code is known, Open <uri> in your browser and and enter code: <code>). It does not show a Ctrl-C hint.
• LoggedIn → briefly Starting terminal…, then the zero state (Warp Agent + version, a "What's new" list, and the project context section) with the input view.
• Failed → Login failed: <message> followed by Press Ctrl-C to exit.

(Exact strings live in crates/warp_tui/src/ui.rs — verify against it if you're asserting on placeholder text.)

So: if your change is on the login placeholder or a pure element/layout, the logged-out OSS build is enough. If your change is in the live terminal / transcript / input surface, you must reach the authenticated state (see the next section), or your change will sit behind the login gate and you'll only ever see Sign in to continue.

Logging in non-interactively (WARP_API_KEY)

You can reach the authenticated (LoggedIn) state headlessly — no browser, no device-auth flow — by launching a dogfood-channel TUI binary with a WARP_API_KEY in the environment. This is the fast way to verify live terminal/transcript/input changes.

Key constraints:

• Dogfood channels only. API-key login is gated to dogfood channels (dev, local) behind the APIKeyAuthentication flag, so it works with warp-tui-dev (or the internal local binary) — not warp-tui-oss, which is not a dogfood channel and will stay logged out.
• The key must already be in the environment. In a sandbox where WARP_API_KEY is set, a freshly started tmux server inherits it. Never echo, print, or inline the secret value in a command — just rely on the inherited environment variable. (--api-key <key> on the command line also works but would expose the secret, so prefer the env var.)

cd <warp-repo-root>
CARGO_BUILD_JOBS=2 cargo build -p warp_tui --bin warp-tui-dev
tmux kill-session -t tuicheck 2>/dev/null
# WARP_API_KEY is inherited from the environment by the new tmux server.
tmux new-session -d -s tuicheck -x 120 -y 40 './target/debug/warp-tui-dev'
sleep 20                                      # login + session start
tmux capture-pane -t tuicheck -p              # expect the logged-in zero state

When it works you'll see the zero state (Warp Agent + input view + model selector) instead of Sign in to continue, and you can send-keys a real prompt and read the agent's reply back with capture-pane. (This login path was added in warpdotdev/warp#13583.)

Step 2 — Run under tmux and read the frame back

The TUI needs a real interactive PTY — a tmux pane is exactly that, and it lets you both send input and read the rendered screen back as text. Start the TUI in a detached session with an explicit size (don't skip -x/-y; a degenerate 1-row pane renders nothing useful):

cd <warp-repo-root>
tmux kill-session -t tuicheck 2>/dev/null   # clear any prior run
tmux new-session -d -s tuicheck -x 120 -y 40 './target/debug/warp-tui-oss'
sleep 1                                       # let it draw + probe the terminal
tmux capture-pane -t tuicheck -p              # <-- the rendered screen, as text

tmux capture-pane -p prints the pane's current contents (the TUI's alternate screen) to stdout, so you read the real frame directly and assert on it. Add -e to include ANSI escape sequences when you need to check colors/styles:

tmux capture-pane -t tuicheck -p -e          # includes color/style escapes

Drive interactions with tmux send-keys, sleeping to let the UI settle, then capture again. For example (type a line, submit it, wait, then read the screen):

tmux send-keys -t tuicheck "What is 2+2? Answer in one short sentence." && \
  sleep 1 && tmux send-keys -t tuicheck Enter && sleep 5 && \
  tmux capture-pane -t tuicheck -p -e

Send special keys by name (Enter, Escape, C-c for Ctrl-C, Up/Down). When done, tear the session down: tmux kill-session -t tuicheck.

Iterate loop

Because incremental rebuilds are ~10s, iterate tightly: edit the TUI code → cargo build -p warp_tui --bin warp-tui-oss → tmux kill-session + restart the session → capture-pane and compare. Verified before/after example: changing the login placeholder string and rebuilding flips the captured line from Sign in to continue to the new text, visible directly in capture-pane output.

Step 3 — Check the captured frame against your change

You have the real screen text, so verify it yourself: grep/scan the capture-pane output for the exact string or layout your change should produce, and diff the before/after captures. No watcher interpretation needed — if the expected text isn't in the capture, the change isn't rendering.

Pitfalls (learned hands-on)

• Run it in a real terminal / tmux pane (a PTY), and drive + capture it via tmux as above.

• If it exits (code 101) right after the first frame instead of staying up: don't assume it's a terminal/stdin problem — check the TUI log first: tail -40 ~/.local/state/warp-terminal-tui/oz/warp-tui.log. One cause seen in the headless OSS/logged-out sandbox build is a debug-only binding-validation panic: crates/warpui_core/src/keymap/matcher.rs (validate_bindings, gated on #[cfg(debug_assertions)]) panics with Bindings failed validation when a keystroke binding matches a TUI keymap context without being TUI-owned (it was app:reopen_closed_session, Ctrl+Alt+T). It does not reproduce in every setup — it depends on which keystroke bindings the running config loads, and the validator exempts non-keystroke (palette/custom) triggers — so treat this as one thing to check, not a guarantee. If you hit it, two ways to still verify a change:

  • Build --release — the validator is compiled out, so the TUI stays up and you can send-keys/capture-pane freely: cargo build --release -p warp_tui --bin warp-tui-oss then run ./target/release/warp-tui-oss.

  • Or poll capture-pane right after launch on the debug build to grab the first frame before the panic:

    tmux new-session -d -s tuicheck -x 120 -y 40 './target/debug/warp-tui-oss'
    for i in $(seq 1 15); do
      frame=$(tmux capture-pane -t tuicheck -p | sed 's/[[:space:]]*$//' | grep .)
      [ -n "$frame" ] && { echo "$frame"; break; }
      sleep 0.2
    done
    tmux kill-session -t tuicheck 2>/dev/null
    

  If the debug build stays up on your machine, you can send-keys/capture-pane repeatedly without racing.

• Alt screen is handled for you. capture-pane reads the alternate screen, so you don't need to fight escape-sequence soup the way piping stdout would.

• Startup probe. On launch the TUI emits terminal probes (OSC 10/11 + a device-attributes query) to pick a theme; a normal tmux pane answers them. Give it ~0.5–1s (a sleep) before the first capture.

• Quitting. Ctrl-C is tmux send-keys -t tuicheck C-c. On the login placeholder one Ctrl-C exits; in a live session it's press-again-to-exit (first press cancels/clears input and arms a ~1s window; a second within the window exits). Always tmux kill-session at the end so a stray session doesn't linger.

Step 4 — Lock it in with a snapshot test

A live run proves the change works now; it is not a regression guard. For any non-trivial TUI rendering/behavior change, add or update a render-to-lines unit test (warpui_core::elements::tui::test_support::render_to_lines / TuiBuffer::to_lines) per tui-testing, and run:

cargo nextest run -p warp_tui
cargo nextest run -p warpui_core

Evidence for the PR

For a user-visible TUI change, attach the concrete rendered result — the relevant lines from tmux capture-pane (and/or the render_to_lines snapshot diff) — as the verification evidence. This is the TUI equivalent of the GUI's computer_use screenshot (see the TUI caveat in review-pr-local).

Related skills

tui-ui-guidelines (the TuiElement cell-grid library) and tui-testing (render-to-lines unit tests) are companion TUI skills added alongside this one; land them together. This skill's build/run/capture workflow stands on its own — those cover authoring TUI UI and writing durable tests.

GUI-only counterparts (do not use for TUI work): gui-integration-test, gui-integration-test-video, gui-onboarding-verification-skill.