tui-debug-in-pane
The tui-debug-in-pane skill launches the ralph TUI application in a dedicated tmux split pane while keeping the main pane available for inspection commands. Use this to isolate and capture TUI rendering bugs, streaming issues, and output corruption that only appear during live execution, enabling diagnosis through captured pane output and diagnostic logs without interrupting your working environment.
git clone --depth 1 https://github.com/mikeyobrien/ralph-orchestrator /tmp/tui-debug-in-pane && cp -r /tmp/tui-debug-in-pane/.claude/skills/tui-debug-in-pane ~/.claude/skills/tui-debug-in-paneSKILL.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
```bash
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).
```bash
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
```bash
rm -f .ralph/loop.lock
git worktree prune
```
### 4. Launch Ralph
```bash
# 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
```bash
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
```bash
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.Guides implementation of code tasks using test-driven development in an Explore, Plan, Code, Commit workflow. Acts as a Technical Implementation Partner and TDD Coach — following existing patterns, avoiding over-engineering, and producing idiomatic, modern code.
Use this agent when you need to run the Ralph orchestrator end-to-end test suite, analyze diagnostic outputs, and generate comprehensive reports of findings. This includes validating backend connectivity, orchestration loop behavior, event parsing, hat collections, memory systems, and error handling. Invoke this agent after making changes to core orchestration logic, before releases, or when debugging integration issues.\\n\\nExamples:\\n\\n<example>\\nContext: User has made changes to the event parsing logic and wants to verify nothing is broken.\\nuser: \"I just modified the event parsing in ralph-core, can you verify everything still works?\"\\nassistant: \"I'll use the ralph-e2e-verifier agent to run the full E2E test suite and analyze the results.\"\\n<Task tool invocation to launch ralph-e2e-verifier>\\n</example>\\n\\n<example>\\nContext: User is preparing a release and needs validation.\\nuser: \"We're preparing to release v0.5.0, please run the E2E tests\"\\nassistant: \"I'll launch the ralph-e2e-verifier agent to run comprehensive E2E tests across all backends and generate a release readiness report.\"\\n<Task tool invocation to launch ralph-e2e-verifier>\\n</example>\\n\\n<example>\\nContext: User notices orchestration issues and wants diagnostics analyzed.\\nuser: \"Ralph seems to be selecting the wrong hats, can you investigate?\"\\nassistant: \"I'll use the ralph-e2e-verifier agent to run E2E tests with diagnostics enabled and analyze the hat selection decisions.\"\\n<Task tool invocation to launch ralph-e2e-verifier>\\n</example>
Use this agent when you need to execute a Ralph orchestration loop end-to-end and verify its completion. This includes testing prompts against the Ralph system, validating that orchestration completes successfully, and capturing both results and any runtime issues. Examples:\\n\\n<example>\\nContext: User wants to test if a prompt works correctly with Ralph orchestration.\\nuser: \"Test if Ralph can handle the prompt 'create a hello world function'\"\\nassistant: \"I'll use the ralph-loop-runner agent to execute this prompt through Ralph and verify completion.\"\\n<Task tool call to ralph-loop-runner agent>\\n</example>\\n\\n<example>\\nContext: User is debugging why a Ralph run failed.\\nuser: \"Run this spec through Ralph and tell me what went wrong\"\\nassistant: \"Let me use the ralph-loop-runner agent to execute this and capture any runtime problems.\"\\n<Task tool call to ralph-loop-runner agent>\\n</example>\\n\\n<example>\\nContext: User wants to validate Ralph behavior after code changes.\\nuser: \"I just modified the event parser, can you run a test loop?\"\\nassistant: \"I'll use the ralph-loop-runner agent to run a complete orchestration loop and verify the changes work correctly.\"\\n<Task tool call to ralph-loop-runner agent>\\n</example>
Generates structured .code-task.md files from descriptions or PDD implementation plans. Auto-detects input type, creates properly formatted tasks with Given-When-Then acceptance criteria.
Use when testing Ralph's hat collection presets, validating preset configurations, or auditing the preset library for bugs and UX issues.
Lists all code tasks in the repository with their status, dates, and metadata. Useful for getting an overview of pending work or finding specific tasks.
Transforms a rough idea into a detailed design document with implementation plan. Follows Prompt-Driven Development — iterative requirements clarification, research, design, and planning.
Browser automation via Playwriter (remorses) using persistent Chrome sessions and the full Playwright Page API.