/tui-validate

name: tui-validate
description: Validates Terminal User Interface (TUI) output using freeze for screenshot capture and LLM-as-judge for semantic validation. Supports both visual (PNG/SVG) and text-based validation modes.
type: anthropic-skill
version: "1.0"
metadata:
  internal: true

TUI Validate

Overview

This skill validates Terminal User Interface (TUI) applications by capturing their output and using LLM-as-judge for semantic validation. It leverages [freeze](https://github.com/charmbracelet/freeze) from Charmbracelet for high-fidelity terminal screenshots and provides structured validation criteria.

**Philosophy**: Rather than brittle string matching, this skill uses semantic understanding to validate that TUI output "looks right" - checking layout, content presence, and visual hierarchy without breaking on minor formatting changes.

When to Use

• Validating TUI rendering after changes
• Checking that UI components display correctly
• Visual regression testing for terminal applications
• Verifying TUI state after specific interactions
• Creating documentation screenshots with validation

Prerequisites

**Required:**

• `freeze` CLI tool installed (`brew install charmbracelet/tap/freeze`)
• `tmux` for interactive TUI capture (optional, for live applications)

**Verification:**

# Check freeze is installed
freeze --version

# Check tmux is installed (for interactive capture)
tmux -V

Parameters

• **target** (required): What to validate. One of:
• `file:<path>` - ANSI output file to validate
• `command:<cmd>` - Command to execute and capture
• `tmux:<session>` - Live tmux session to capture
• `buffer:<text>` - Raw text/ANSI to validate

• **criteria** (required): Validation criteria. Can be:
• A predefined criteria name (see Built-in Criteria)
• A custom criteria string describing what to check

• **output_format** (optional, default: "svg"): Screenshot format
• `svg` - Vector format, best for documentation
• `png` - Raster format, best for visual diff
• `text` - Text-only extraction, fastest

• **save_screenshot** (optional, default: false): Whether to save the screenshot
• If true, saves to `{target_name}.{format}` in current directory

• **judge_mode** (optional, default: "semantic"): Validation approach
• `semantic` - LLM judges based on meaning and layout
• `strict` - Also checks exact content presence
• `visual` - Requires PNG, checks visual appearance

Built-in Criteria

`ralph-header`

Validates Ralph TUI header component:

• Iteration counter in `[iter N]` or `[iter N/M]` format
• Elapsed time in `MM:SS` format
• Hat indicator with emoji and name
• Mode indicator (`▶ auto` or `⏸ paused`)
• Optional scroll mode indicator `[SCROLL]`
• Optional idle countdown `idle: Ns`

`ralph-footer`

Validates Ralph TUI footer component:

• Activity indicator (`◉ active`, `◯ idle`, or `■ done`)
• Last event topic display
• Search mode display when active

`ralph-full`

Validates complete Ralph TUI layout:

• Header section at top (3 lines)
• Terminal content area (variable height)
• Footer section at bottom (3 lines)
• Proper visual hierarchy and borders

`tui-basic`

Generic TUI validation:

• Has visible content (not blank)
• No rendering artifacts or broken characters
• Proper terminal dimensions

Execution Flow

1. Capture Phase

Capture TUI output based on target type:

**For file targets:**

freeze {file_path} -o /tmp/tui-capture.{format}

**For command targets:**

freeze --execute "{command}" -o /tmp/tui-capture.{format}

**For tmux targets:**

tmux capture-pane -pet {session} | freeze -o /tmp/tui-capture.{format}

**For buffer targets:**

echo "{buffer}" | freeze -o /tmp/tui-capture.{format}

**Constraints:**

• You MUST verify freeze is installed before attempting capture
• You MUST handle capture failures gracefully and report the error
• You MUST use appropriate freeze flags for the output format
• You SHOULD use `--theme base16` for consistent rendering
• You SHOULD set reasonable dimensions with `--width` and `--height`

2. Extraction Phase

Extract content for LLM analysis:

**For text/semantic validation:**

• If format is `text`, use the captured text directly
• If format is `svg` or `png`, also capture text version for content analysis

**For visual validation:**

• Requires PNG format
• Will analyze the image directly using vision capabilities

**Constraints:**

• You MUST extract both visual and text representations when judge_mode is `visual`
• You MUST preserve ANSI escape sequences for color validation when relevant

3. Validation Phase

Apply LLM-as-judge with the appropriate criteria:

**Semantic Validation Prompt Template:**

Analyze this terminal UI output and determine if it meets the following criteria:

CRITERIA:
{criteria_description}

TERMINAL OUTPUT:
{captured_text}

Evaluate each criterion and provide:
1. PASS or FAIL for each requirement
2. Brief explanation for any failures
3. Overall verdict: PASS or FAIL

Be lenient on exact formatting but strict on:
- Required content presence
- Logical layout and hierarchy
- No rendering errors or artifacts

**Visual Validation Prompt Template (with image):**

Examine this terminal screenshot and validate:

CRITERIA:
{criteria_description}

Check for:
1. Visual hierarchy and layout
2. Color coding correctness
3. No rendering artifacts or broken characters
4. Proper alignment and spacing

Verdict: PASS or FAIL with explanation

**Constraints:**

• You MUST return a clear PASS or FAIL verdict
• You MUST provide specific feedback on failures
• You MUST be lenient on whitespace/formatting differences
• You MUST be strict on content presence and semantic correctness
• You SHOULD note any warnings even on PASS results

4. Reporting Phase

Report validation results:

**On PASS:**

✅ TUI Validation PASSED

Criteria: {criteria_name}
Target: {target}
Mode: {judge_mode}

All requirement