Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: Add tmux-cli as preferred debugging method

Maximilian Roos4af44b76633f
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index 5afd631c3..cd7cd50f2 100644
--- a/src/commands/CLAUDE.md
+++ b/src/commands/CLAUDE.md
@@ -1,6 +1,6 @@
# Debugging Interactive Terminal Commands
-When debugging TUI commands like `wt beta select`, use MCP's `node-terminal` tools to test interactively.
+When debugging TUI commands like `wt beta select`, use the `tmux-cli` skill (preferred) or MCP's `node-terminal` tools to test interactively.
## Debugging Workflow
@@ -12,7 +12,33 @@ cargo run --bin setup-select-test
This creates a reproducible test repo at `/tmp/wt-select-test/test-repo`.
-### 2. Test in MCP Terminal
+### 2. Test Interactively
+
+#### Option A: tmux-cli skill (preferred, if available)
+
+Load the `tmux-cli` skill, then use the `tmux-cli` tool. Install if needed: `uv tool install claude-code-tools` (requires tmux).
+
+```bash
+# Launch shell in test repo
+pane=$(tmux-cli launch "zsh")
+tmux-cli send "cd /tmp/wt-select-test/test-repo" --pane=$pane
+tmux-cli wait_idle --pane=$pane
+
+# Run with debug logging
+tmux-cli send "RUST_LOG=worktrunk=debug cargo run --quiet -- beta select 2> debug.log" --pane=$pane
+tmux-cli wait_idle --pane=$pane
+
+# Test interaction (e.g., select option 3)
+tmux-cli send "3" --pane=$pane
+tmux-cli wait_idle --pane=$pane
+
+# Capture output
+tmux-cli capture --pane=$pane
+```
+
+#### Option B: MCP node-terminal
+
+MCP terminals use pseudo-TTY, not real terminals. If tests pass in MCP but users report issues, the bug is likely environment-specific. Always test on the actual problematic repository.
```typescript
// Create terminal and navigate to test repo
@@ -23,7 +49,7 @@ mcp__node-terminal__terminal_send_key({ sessionId: "test", key: "enter" })
// Run with debug logging
mcp__node-terminal__terminal_write({
sessionId: "test",
- input: "RUST_LOG=worktrunk=debug cargo run --quiet -- beta select 2> test.log"
+ input: "RUST_LOG=worktrunk=debug cargo run --quiet -- beta select 2> debug.log"
})
mcp__node-terminal__terminal_send_key({ sessionId: "test", key: "enter" })
@@ -32,19 +58,7 @@ mcp__node-terminal__terminal_write({ sessionId: "test", input: "3" })
mcp__node-terminal__terminal_read({ sessionId: "test" })
```
-### 3. If Synthetic Test Works But User Reports Issues
-
-**Test on the actual repository!** Environment-specific issues (git config, shell config) won't appear in isolated test environments.
-
-```typescript
-// Use -C to test in user's actual repo
-mcp__node-terminal__terminal_write({
- sessionId: "test",
- input: "RUST_LOG=worktrunk=debug cargo run --quiet -- -C /path/to/actual/repo beta select 2> debug.log"
-})
-```
-
-### 4. Analyze Logs
+### 3. Analyze Logs
```bash
tail -100 debug.log | grep -E "error|hang|stuck"
@@ -63,10 +77,6 @@ cargo run --quiet -- -C /path/to/repo beta select
wt --source -C /path/to/repo beta select
```
-## MCP Limitations
-
-MCP terminals use pseudo-TTY, not real terminals. If tests pass in MCP but users report issues, the bug is likely environment-specific. Always test on the actual problematic repository.
-
## Shell Completion for CLI Arguments
Branch and worktree arguments should include shell completion for better UX. Add completion helpers to CLI definitions: