tui-debug-in-pane
Use when you need to reproduce or debug TUI rendering issues (garbled output, broken streaming, layout corruption) by running ralph in a tmux split pane and capturing live output.
- License 许可
- MIT
- 最近更新
- 2026-09-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tui-debug-in-pane
- metadata
- { "internal": true }
- description
- Use when you need to reproduce or debug TUI rendering issues (garbled output, broken streaming, layout corruption) by running ralph in a tmux split pane and capturing live output.
03 SKILL.md 正文
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
sleep 20 # Pi/Kiro take 15-30s to start streaming
tmux capture-pane -t PANE -p -S -60
ls -lt .ralph/diagnostics/logs/ | head -5
6. Clean Up
tmux send-keys -t PANE q
tmux send-keys -t PANE C-c
tmux kill-pane -t PANE
Common Mistakes
- Shell mismatch: Split panes get bash by default. If tools fail with "command not found", switch to fish with
exec /path/to/fish. - Stale loop lock: If
.ralph/loop.lockexists, ralph spawns worktree loops instead of running normally. Always delete it first. - Wrong backend in TUI header: Without
cli.backend: piin the config, ralph uses claude regardless of hat settings. - Missing hat
namefield: HatConfig requiresname; omitting it causes a config parse error. - Premature capture: Pi and Kiro take 15-30s before streaming text appears. Capture too early and you see an empty content area.
- Ghost keystrokes: If the TUI already exited, pressing
qprepends it to your next command. Check if the TUI is still running before sending quit keys.
04 同仓库更多 Skills
ralph-loop
Run, monitor, resume, merge, and debug Ralph loops. Use this skill whenever the user asks to operate `ralph run` or `ralph loops`, inspect loop state, recover suspended loops, analyze diagnostics, or unblock merge queue issues.
ralph-hats
Create, inspect, validate, explain, and improve Ralph hat collections. Use this skill whenever the user asks to make or refine a `.ralph/hats/*.yml` workflow, debug hat routing, explain event topology, or tune a multi-hat Ralph run.
ralph-docs
Introspect, explain, and improve ralph-jev-gauntlet using the documentation shipped in its repository. Use this skill whenever the user asks questions about Ralph's behavior, wants to understand how a Ralph internal works (event loop, gauntlet gate, judge evidence, Jev hooks, parallel loops, configuration), debug an unfamiliar failure mode, or propose a code change to the ralph-jev-gauntlet repo. The skill teaches the agent to answer from the repo's docs and source before guessing, and to scope improvements through the documented architecture rather than the local checkout alone.
complex-test-skill
A directory-style test skill for smoke testing
tui-validate
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.
tmux-terminal
Interactive terminal control via tmux for TUI apps, prompts, and long-running CLI workflows.