A TUI testing toolkit for programmatic interaction with terminal applications. Built in Zig on Ghostty's ghostty-vt terminal emulation core.

Developed specifically to test Bubble Tea interfaces agentically — letting AI agents spawn, drive, and assert against TUI applications through MCP without needing a display.

• macOS (aarch64, x86_64)
• Linux (x86_64)

# macOS (Apple Silicon)
curl -fsSL https://github.com/hegner123/tui-test-ghost/releases/latest/download/tui-test-ghost-v0.3.0-macos-aarch64.tar.gz | tar xz
mv tui-test-ghost /usr/local/bin/

# Linux (x86_64)
curl -fsSL https://github.com/hegner123/tui-test-ghost/releases/latest/download/tui-test-ghost-v0.3.0-linux-x86_64.tar.gz | tar xz
mv tui-test-ghost /usr/local/bin/

Requires Zig 0.15.1+. Ghostty is fetched automatically.

git clone https://github.com/hegner123/tui-test-ghost.git
cd tui-test-ghost
zig build -Doptimize=ReleaseSafe
just install

claude mcp add tui-test-ghost -- tui-test-ghost

tui-test-ghost

Starts a JSON-RPC MCP server on stdin/stdout with these tools:

tui-test-ghost replay test.jsonl

Replays a recorded JSONL session and reports pass/fail for each entry. Action tools (tui_start, tui_send, tui_screen, tui_cell, tui_resize) are re-executed without comparison. Assertion tools (tui_wait, tui_stop, tui_snapshot) compare key result fields against the recorded values.

Exits 0 if all assertions pass, 1 if any fail. Single-session recordings only (one tui_start per file).

JSONL format — one JSON object per line:

{"tool":"tui_start","args":{"command":"myapp"},"result":{"session_id":0,"text":"..."}}
{"tool":"tui_send","args":{"session_id":0,"keys":["down*3","enter"]},"result":{"text":"..."}}
{"tool":"tui_wait","args":{"session_id":0,"text":"Settings"},"result":{"matched":true,"text":"..."}}
{"tool":"tui_stop","args":{"session_id":0},"result":{"exit_code":0}}

tui-test-ghost --cli --command htop --screen
tui-test-ghost --cli --command vim --send "ihello" --wait-for "hello" --screen

• Real terminal emulation — Ghostty's VT parser handles SGR, cursor movement, alternate screen buffer, scrollback
• PTY-based — programs run in a real pseudo-terminal, behaving exactly as they would in a real terminal
• Cell-level inspection — query individual cell attributes: character, bold, italic, underline, strikethrough, dim, foreground/background color (default, palette, RGB)
• Wait conditions — poll until text appears, screen stabilizes, cursor reaches a position, or process exits
• Golden file snapshots — capture screen state to disk, diff against a baseline on future runs
• Session pool — manage up to 16 concurrent terminal sessions
• Keyboard input — send named keys (enter, tab, escape, arrows, F1-F12) with modifier combinations (ctrl, alt, shift)
• Key batching — send multiple keystrokes in a single MCP call with the keys array: ["down*5", "enter"]
• Auto-screen — tui_start, tui_send, tui_wait, and tui_resize return screen state in every response
• Region cropping — return only a portion of the screen with the region parameter to reduce token usage
• Resize — change terminal dimensions mid-session, delivering SIGWINCH to the child process
• Record/replay — record an agent's MCP tool calls to JSONL, replay them as a repeatable test suite with tui-test-ghost replay

The keys parameter on tui_send accepts an array of string tokens:

The text: prefix is reserved. Max 64 tokens per call, max 99 repeats.

Tools that return screen content accept an optional region object to crop the output:

{"region": {"row": 2, "col": 0, "width": 40, "height": 10}}

All fields are optional (defaults: row=0, col=0, width=terminal cols, height=terminal rows). Values are clamped to terminal bounds.

TUI Process → PTY → ghostty-vt Terminal Emulator → Screen Query API → MCP / CLI

Programs run in a real PTY backed by Ghostty's VT parser, providing accurate screen state including SGR attributes, cursor positioning, and alternate screen buffer support. Single-threaded with explicit drain — the caller controls when PTY output is consumed and fed to the terminal emulator.

See CONTRIBUTING.md.

MIT License. See LICENSE.