tui-dev

name	tui-dev
description	Develop, test, and validate Terminal User Interface applications using tmux as your "headless browser" for terminals. Use when asked to run a TUI application, capture its output, verify its behavior, or debug rendering issues. This skill provides a structured workflow for TUI development, including session management, interaction patterns, state capture, and regression detection.

Develop, test, and validate Terminal User Interface applications using tmux as your "headless browser" for terminals.

Philosophy

TUI development presents unique challenges for AI agents: the output is visual and not easily parseable. This skill enables a visual verification loop:

1. Make code changes
2. Run the TUI in a controlled tmux environment
3. Capture and analyze the visual output
4. Determine if changes achieved the desired effect

tmux serves as the equivalent of a headless browser for terminal applications—it provides a controlled, scriptable environment to run and interact with TUIs without requiring a physical terminal.

---

Prerequisites

# Install freeze (Charm's terminal screenshot tool)
brew install charmbracelet/tap/freeze

# Verify tmux is available
which tmux

---

1. tmux Fundamentals

Session Management

# Create a detached session with specific dimensions
tmux new-session -d -s <session-name> -x <cols> -y <rows> '<command>'

# List sessions
tmux list-sessions

# Attach to session (for debugging)
tmux attach-session -t <session-name>

# Kill session
tmux kill-session -t <session-name>

# Kill all sessions (cleanup)
tmux kill-server

Terminal Environment

Set these environment variables for proper TUI rendering:

TERM=xterm-256color        # 256 color support
COLORTERM=truecolor        # 24-bit color support
LANG=en_US.UTF-8           # Unicode support
LC_ALL=en_US.UTF-8

# Full example
tmux new-session -d -s tui -x 120 -y 40 \
  'TERM=xterm-256color COLORTERM=truecolor ./my-tui-app'

Size Guidelines

Use Case	Size	Flags
Standard TUI	80x24	-x 80 -y 24
Wide tables/dashboards	120x40	-x 120 -y 40
Full-screen TUI	160x50	-x 160 -y 50
Mobile/narrow testing	60x20	-x 60 -y 20
Documentation screenshots	100x30	-x 100 -y 30

---

2. Running TUI Applications

Basic Patterns

# Run a binary
tmux new-session -d -s app -x 80 -y 24 './my-tui-app'

# With build step (Rust)
cargo build --release && \
  tmux new-session -d -s app -x 80 -y 24 './target/release/my-tui'

# With arguments
tmux new-session -d -s app -x 80 -y 24 './my-app --config config.toml'

# From specific directory
tmux new-session -d -s app -x 80 -y 24 -c /path/to/project './app'

Language-Specific Examples

# Rust (ratatui, crossterm)
cargo run --release

# Go (bubbletea, tview)
go run .

# Python (textual, rich)
python -m myapp

# Node.js (blessed, ink)
npx tsx ./src/app.tsx

Handling Startup Time

# Fixed delay (simple)
sleep 2

# Poll for specific content (more reliable)
for i in {1..30}; do
  tmux capture-pane -t app -p | grep -q "Ready" && break
  sleep 0.1
done

# Wait for any content to appear
until tmux capture-pane -t app -p 2>/dev/null | grep -q .; do
  sleep 0.1
done

---

3. Interacting with TUI Applications

send-keys Basics

# Send literal text
tmux send-keys -t <target> 'text'

# Send special keys
tmux send-keys -t app Enter
tmux send-keys -t app Escape
tmux send-keys -t app Tab
tmux send-keys -t app Space
tmux send-keys -t app BSpace    # Backspace

Key Reference

Action	tmux Key
Enter/Return	Enter
Escape	Escape
Tab	Tab
Shift+Tab	S-Tab or BTab
Backspace	BSpace
Delete	DC
Home	Home
End	End
Page Up	PgUp
Page Down	PgDn
Arrow keys	Up, Down, Left, Right
Function keys	F1 through F12
Ctrl+key	C-<key> (e.g., C-c, C-a)
Alt+key	M-<key> (e.g., M-x)
Ctrl+Alt+key	C-M-<key>

Timing Between Actions

# Bad: no delay
tmux send-keys -t app 'j' && tmux send-keys -t app Enter

# Good: small delay for TUI to process
tmux send-keys -t app 'j'
sleep 0.1
tmux send-keys -t app Enter

# Better: wait for expected state
tmux send-keys -t app 'j'
until tmux capture-pane -t app -p | grep -q "item 2"; do sleep 0.05; done
tmux send-keys -t app Enter

Complex Interactions

# Navigate a menu
tmux send-keys -t app Down Down Enter
sleep 0.2

# Type into an input field
tmux send-keys -t app 'my search query' Enter

# Open command palette
tmux send-keys -t app C-p
sleep 0.1
tmux send-keys -t app 'command name' Enter

# Scroll through content
for i in {1..10}; do
  tmux send-keys -t app Down
  sleep 0.05
done

---

4. Observing and Capturing State

capture-pane Options

# Basic capture with ANSI colors
tmux capture-pane -t <target> -p -e > output.txt

# Capture specific line range
tmux capture-pane -t app -p -e -S 0 -E 20 > output.txt

# Include scrollback history
tmux capture-pane -t app -p -e -S -1000 > output.txt

Flag	Purpose
-p	Print to stdout (instead of tmux buffer)
-e	Include ANSI escape sequences (colors)
-S n	Start line (negative = scrollback)
-E n	End line
-J	Join wrapped lines

Reading Content Programmatically

# Search for content
tmux capture-pane -t app -p | grep -q "Error" && echo "Error found!"

# Check for UI element
if tmux capture-pane -t app -p | grep -q "Save successful"; then
  echo "Save completed"
fi

# Get specific line
tmux capture-pane -t app -p | sed -n '5p'

# Count occurrences
tmux capture-pane -t app -p | grep -c "item"

Screenshots with freeze

# Capture terminal content
tmux capture-pane -t app -p -e > .agent/tui-dev/capture.txt

# Basic PNG
freeze .agent/tui-dev/capture.txt -o screenshot.png

# Styled screenshot
freeze .agent/tui-dev/capture.txt -o screenshot.png \
  --theme dracula \
  --padding 20 \
  --margin 20 \
  --border.radius 8 \
  --shadow.blur 20 \
  --font.family "JetBrains Mono" \
  --font.size 14 \
  --window

# SVG output (scalable)
freeze .agent/tui-dev/capture.txt -o screenshot.svg

freeze Options

Option	Description	Example
--theme	Color theme	dracula, monokai, nord
--padding	Internal padding (px)	20
--margin	External margin (px)	20
--border.radius	Corner radius	8
--shadow.blur	Shadow blur radius	20
--font.family	Font name	"JetBrains Mono"
--font.size	Font size	14
--window	Show window chrome	(flag)
-o	Output file	.png, .svg, .webp

State Comparison

# Capture "before" state
tmux capture-pane -t app -p > .agent/tui-dev/before.txt

# Make interaction
tmux send-keys -t app Enter
sleep 0.5

# Capture "after" state
tmux capture-pane -t app -p > .agent/tui-dev/after.txt

# Compare
diff .agent/tui-dev/before.txt .agent/tui-dev/after.txt

---

5. AI Agent Development Loop

The Workflow

┌──────────────────────────────────────────────────────────┐
│                  TUI Development Loop                     │
├──────────────────────────────────────────────────────────┤
│                                                           │
│   ┌────────┐    ┌────────┐    ┌────────┐                 │
│   │ 1.Edit │───▶│2.Build │───▶│ 3.Run  │                 │
│   │  Code  │    │  App   │    │in tmux │                 │
│   └────────┘    └────────┘    └────────┘                 │
│        ▲                           │                      │
│        │                           ▼                      │
│   ┌────────┐    ┌────────┐    ┌────────┐                 │
│   │ 6.Fix  │◀───│5.Verify│◀───│4.Capture│                │
│   │ Issues │    │ State  │    │ Output │                 │
│   └────────┘    └────────┘    └────────┘                 │
│                                                           │
└──────────────────────────────────────────────────────────┘

Complete Development Cycle

# === 1. Edit code ===
# (Make code changes with Edit tool)

# === 2. Build ===
cargo build --release
if [ $? -ne 0 ]; then
  echo "Build failed"
  exit 1
fi

# === 3. Start TUI ===
tmux kill-session -t tui 2>/dev/null || true
tmux new-session -d -s tui -x 120 -y 40 \
  'TERM=xterm-256color ./target/release/my-tui'
sleep 2

# === 4. Capture state ===
mkdir -p .agent/tui-dev
tmux capture-pane -t tui -p -e > .agent/tui-dev/state.txt

# === 5. Verify ===
# Check for expected content
if ! grep -q "Welcome" .agent/tui-dev/state.txt; then
  echo "ERROR: Welcome message not displayed"
fi

# Check for errors
if grep -q "Error\|panic\|crash" .agent/tui-dev/state.txt; then
  echo "ERROR: Crash detected"
fi

# === 6. Interactive verification ===
tmux send-keys -t tui Tab
sleep 0.2
tmux send-keys -t tui Enter
sleep 0.5
tmux capture-pane -t tui -p -e > .agent/tui-dev/state-after.txt

if grep -q "Feature Active" .agent/tui-dev/state-after.txt; then
  echo "SUCCESS: Feature working"
fi

# === Cleanup ===
tmux kill-session -t tui

Validation Helper Patterns

# Assert content present
assert_content() {
  local pattern="$1"
  local target="${2:-tui}"
  if ! tmux capture-pane -t "$target" -p | grep -q "$pattern"; then
    echo "FAIL: Expected '$pattern' not found"
    return 1
  fi
  echo "PASS: Found '$pattern'"
}

# Assert content absent
assert_no_content() {
  local pattern="$1"
  local target="${2:-tui}"
  if tmux capture-pane -t "$target" -p | grep -q "$pattern"; then
    echo "FAIL: Unexpected '$pattern' found"
    return 1
  fi
  echo "PASS: '$pattern' correctly absent"
}

# Wait for content with timeout
wait_for_content() {
  local pattern="$1"
  local timeout="${2:-30}"
  local target="${3:-tui}"

  for i in $(seq 1 $timeout); do
    if tmux capture-pane -t "$target" -p | grep -q "$pattern"; then
      return 0
    fi
    sleep 0.1
  done
  echo "TIMEOUT: '$pattern' not found after ${timeout}00ms"
  return 1
}

Regression Detection

# Save known-good state as golden file
tmux capture-pane -t tui -p > .agent/tui-dev/golden/main-screen.txt

# Compare current state against golden
tmux capture-pane -t tui -p > .agent/tui-dev/current.txt

# Strip ANSI codes for content comparison
strip_ansi() {
  sed 's/\x1b\[[0-9;]*m//g'
}

diff <(strip_ansi < .agent/tui-dev/golden/main-screen.txt) \
     <(strip_ansi < .agent/tui-dev/current.txt)

---

6. Troubleshooting

Common Issues

Problem	Cause	Solution
App exits immediately	Missing TTY	Run inside tmux session
No colors in capture	Missing -e flag	Add -e to capture-pane
Wrong dimensions	Not set explicitly	Use -x and -y flags
Keys not registering	Too fast	Add sleep 0.1 between sends
Unicode garbled	Locale issue	Set LANG=en_US.UTF-8
App unresponsive	Wrong TERM	Try TERM=xterm-256color

Debugging Rendering

# Check TERM value
tmux send-keys -t app 'echo $TERM' Enter
sleep 0.5
tmux capture-pane -t app -p | tail -2

# Verify color support
tmux send-keys -t app 'tput colors' Enter
sleep 0.5
tmux capture-pane -t app -p | tail -2

# Check for ANSI codes in capture
cat -v .agent/tui-dev/capture.txt | head -10
# Should show ^[[38;5;... sequences

# Verify session dimensions
tmux display-message -t app -p '#{window_width}x#{window_height}'

Handling Crashes

# Check if session exists
tmux has-session -t tui 2>/dev/null
echo $?  # 0 = exists, 1 = gone

# Check running process
tmux list-panes -t tui -F '#{pane_pid} #{pane_current_command}'

# Capture crash output before cleanup
tmux capture-pane -t tui -p -e -S -1000 > .agent/tui-dev/crash-log.txt

---

Directory Convention

Use .agent/tui-dev/ for TUI development artifacts:

.agent/tui-dev/
├── captures/          # Raw terminal captures
│   ├── current.txt
│   └── before.txt
├── screenshots/       # Generated images
│   └── feature.png
├── golden/            # Reference states for regression
│   └── main-screen.txt
└── logs/              # Build/crash logs
    └── crash-log.txt

---

Quick Reference

# Start TUI in tmux
tmux new-session -d -s tui -x 120 -y 40 'TERM=xterm-256color ./app'

# Wait for startup
sleep 2

# Send keystrokes
tmux send-keys -t tui Down Enter

# Capture output
tmux capture-pane -t tui -p -e > .agent/tui-dev/output.txt

# Take screenshot
freeze .agent/tui-dev/output.txt -o screenshot.png --theme nord

# Check for content
tmux capture-pane -t tui -p | grep -q "Success" && echo "OK"

# Cleanup
tmux kill-session -t tui