tui-debug-in-pane

Debug TUI rendering bugs by launching ralph in a tmux split pane and capturing live output. The split keeps your main pane free for inspection commands.

When to Use

• Reproducing garbled or corrupted TUI output from a specific provider
• Investigating streaming rendering issues that only appear live
• Capturing TUI state for bug reports or diagnostics

Quick Reference

Task	Command
Identify current pane	tmux display-message -p '#{session_name}:#{window_index}.#{pane_index}'
Create split pane	tmux split-window -h -t SESSION:WINDOW -c /path/to/repo
List panes	tmux list-panes -t SESSION:WINDOW
Fix shell in pane	tmux send-keys -t PANE "exec /path/to/fish" Enter
Send command	tmux send-keys -t PANE "command" Enter
Capture output	tmux capture-pane -t PANE -p -S -60
Quit TUI	tmux send-keys -t PANE q
Force stop	tmux send-keys -t PANE C-c
Kill split pane	tmux kill-pane -t PANE

Procedure

1. Create the Split Pane

tmux display-message -p '#{session_name}:#{window_index}.#{pane_index}'
tmux split-window -h -t SESSION:WINDOW -c /path/to/repo
tmux list-panes -t SESSION:WINDOW

2. Fix Shell Environment

Split panes inherit the tmux server's default shell (bash), not the parent's. Tools like pi need fish (mise/Node).

tmux send-keys -t PANE "exec /nix/store/km9w9r1p4nl92y5fp4vfwsjymjig4axl-fish-3.7.1/bin/fish" Enter
tmux send-keys -t PANE "which pi && pi --version" Enter

3. Clean Up Before Running

rm -f .ralph/loop.lock
git worktree prune

4. Launch Ralph

# Prefer release binary (faster startup)
tmux send-keys -t PANE "target/release/ralph run -c CONFIG.yml -p 'prompt' --max-iterations N" Enter

# Or with cargo (must specify --bin for this workspace)
tmux send-keys -t PANE "cargo run --bin ralph -- run -c CONFIG.yml -p 'prompt' --max-iterations N" Enter

5. Capture and Analyze