AGENT SKILL

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.lock exists, ralph spawns worktree loops instead of running normally. Always delete it first.
  • Wrong backend in TUI header: Without cli.backend: pi in the config, ralph uses claude regardless of hat settings.
  • Missing hat name field: HatConfig requires name; 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 q prepends it to your next command. Check if the TUI is still running before sending quit keys.

04 同仓库更多 Skills

flaviomartil
flaviomartil/ralph-jev-gauntlet

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.

★ 0
flaviomartil
flaviomartil/ralph-jev-gauntlet

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.

★ 0
flaviomartil
flaviomartil/ralph-jev-gauntlet

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.

★ 0
flaviomartil
flaviomartil/ralph-jev-gauntlet

complex-test-skill

A directory-style test skill for smoke testing

★ 0
flaviomartil
flaviomartil/ralph-jev-gauntlet

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.

★ 0
flaviomartil
flaviomartil/ralph-jev-gauntlet

tmux-terminal

Interactive terminal control via tmux for TUI apps, prompts, and long-running CLI workflows.

★ 0