feat: Add tmux integration to /parallel-work start

[evansenter]

Summary

Enhances /parallel-work start to automatically create a tmux pane or window for the new worktree session when running inside tmux.

Changes

• Detect tmux via $TMUX environment variable
• Offer 3 options via AskUserQuestion:
  • New tmux pane (Recommended) - horizontal split, keeps new session visible
  • New tmux window - separate window in current session
  • Manual - original behavior with terminal instructions
• Execute tmux split-window or tmux new-window with the worktree path
• Send claude startup command via tmux send-keys

Test plan

• Run /parallel-work start test-branch inside tmux
• Verify pane option creates horizontal split with claude session
• Verify window option creates new window named after branch
• Verify manual option shows original instructions
• Run /parallel-work start test-branch outside tmux
• Verify only manual instructions are shown (no tmux prompt)

Closes #37

🤖 Generated with Claude Code

[claude]

PR Review: Tmux Integration for /parallel-work

Overview

This PR successfully adds tmux integration to the /parallel-work start command, addressing issue #37. The implementation follows Option 2 from the issue (AskUserQuestion choice), which is a good UX decision.

---

✅ Strengths

1. Well-structured UX flow: The implementation correctly detects tmux via $TMUX and only offers tmux options when available, gracefully degrading to manual instructions otherwise.

2. Clear user choices: The three options (pane/window/manual) are well-differentiated with helpful descriptions. Making "pane" the recommended option is sensible - it keeps the new session visible.

3. Proper tmux command usage:

   • tmux split-window -h -c creates horizontal splits in the worktree directory
   • tmux new-window -c -n properly names the window after the branch
   • tmux send-keys correctly sends the claude startup command

4. Good documentation: The CLAUDE.md update accurately reflects the new functionality.

5. Consistent with existing patterns: Follows the command file format established in the repo, uses AskUserQuestion appropriately.

---

🔍 Issues & Concerns

Critical: Shell Escaping Vulnerability (Security)

Location: Lines 200-201, 207-208

The current implementation has a command injection risk in the tmux send-keys commands.

Problem: If BRANCH_NAME contains special characters (quotes, backticks), this could break the command or execute unintended code.

Recommended fixes:

• Option 1: Escape single quotes properly before interpolation
• Option 2: Use double quotes and escape properly
• Option 3 (Simplest): Avoid interpolation entirely by using generic message

Medium: Missing Full Path Interpolation

Location: Lines 200, 207

The placeholders [full-worktree-path] need to be replaced with actual bash variable interpolation like $WORKTREE_DIR/$BRANCH_NAME

Low: Inconsistent Output Format

Location: Lines 211-225 vs 231-251

The success message differs between tmux auto-launch and manual modes. Consider standardizing the Tips section across both.

---

🧪 Test Coverage

The test plan in the PR description is comprehensive for happy paths. Missing test cases:

1. Branch names with special characters (spaces, quotes, etc.) - critical given the escaping issue
2. What happens if tmux split-window fails (e.g., terminal too small)?
3. Verify the claude command actually starts (not just sent to tmux)

---

📊 Code Quality

Positives:

• Clear step numbering and organization
• Proper JSON formatting for AskUserQuestion
• Good separation of concerns

Suggestions:

1. Add error handling for tmux command failures with fallback to manual instructions
2. Consider storing the tmux command result to verify success

---

🔒 Security Summary

High Priority: Fix command injection vulnerability in tmux send-keys
Medium Priority: Validate BRANCH_NAME earlier in the flow to reject dangerous characters

---

📝 Recommendations

Must Fix Before Merge:

1. Fix command injection risk in tmux send-keys commands (lines 200-201, 207-208)
2. Replace placeholder with proper variable interpolation

Should Consider:

3. Add error handling for tmux command failures
4. Standardize output format between tmux and manual modes
5. Add test cases for edge cases (special characters in branch names)

---

🎉 Conclusion

This is a valuable enhancement that improves the developer workflow significantly. The core implementation is sound and follows the repo conventions well. However, the command injection vulnerability must be addressed before merging.

Recommendation: Request changes for security fix, then approve.

---

Generated with Claude Code

[claude]

PR Review: Tmux Integration for /parallel-work

Summary

This PR enhances the /parallel-work start command with intelligent tmux integration, allowing automatic creation of tmux panes/windows for new worktree sessions. The implementation is well-designed and aligns with the existing command structure.

Code Quality ✅

Strengths:

• Clear instructions: The tmux integration steps are well-documented with explicit bash commands
• Graceful degradation: Properly detects tmux via $TMUX and falls back to manual instructions
• Consistent with existing patterns: Follows the established command file format and uses AskUserQuestion as expected
• Good UX: Recommends the pane option (keeps user in view) over window, with sensible defaults

Suggestions:

1. Quote the worktree path in tmux commands (Security/Robustness)

   Lines 200 and 207 should quote the path arguments to handle edge cases with spaces or special characters:

   # Current:
   tmux split-window -h -c "[full-worktree-path]"
   
   # Recommended:
   tmux split-window -h -c "[full-worktree-path]"

   While the instructions show [full-worktree-path] as a placeholder, Claude should be reminded to quote the actual path when substituting. Consider adding a note: (use proper shell quoting when substituting the path).

2. Error handling for tmux commands (Robustness)

   The tmux commands could fail (e.g., if terminal is too small for split, or tmux session issues). Consider adding validation or a fallback:

   # Create horizontal split, cd to worktree, and start claude
   if ! tmux split-window -h -c "[full-worktree-path]"; then
       echo "⚠️ Failed to create tmux pane. Starting manual instructions:"
       # Fall back to manual instructions
   fi

   Alternatively, document in step 8 that if tmux command fails, Claude should catch the error and provide manual instructions.

3. TMUX detection could be more robust (Minor Enhancement)

   Checking $TMUX is correct, but you could also verify tmux is functional:

   # More robust check
   if [ -n "$TMUX" ] && tmux display-message -p '#S' >/dev/null 2>&1; then
       # tmux is available and working
   fi

Potential Bugs 🐛

1. Missing parameter substitution guidance (Documentation Gap)

   The instructions use placeholders like [full-worktree-path], [branch-name], and [pane/window] but don't explicitly tell Claude to replace them. While Claude will likely infer this, being explicit helps:

   # Add note above commands:
   # Note: Replace placeholders with actual values:
   # - [full-worktree-path]: Use $WORKTREE_DIR/$BRANCH_NAME
   # - [branch-name]: Use $BRANCH_NAME
   # - [pane/window]: Use "pane" or "window" based on user selection

2. Escaped quotes in send-keys command (Potential Shell Issue)

   Line 201 and 208:

   tmux send-keys "claude 'Starting parallel work. Read .parallel-context.md for context.'" Enter

   The nested single quotes inside double quotes are fine, but consider documenting that the command should be passed as-is to avoid shell escaping issues. Alternatively, use a simpler approach:

   tmux send-keys 'claude "Starting parallel work. Read .parallel-context.md for context."' Enter

Performance Considerations ⚡

No significant performance concerns. The tmux commands execute instantly, and the check for $TMUX is a simple environment variable lookup.

Minor optimization:

• The tmux detection (echo "$TMUX") could be combined with the question presentation logic to avoid asking if not in tmux, which the current flow already does correctly.

Security Concerns 🔒

1. Command injection via branch name (Medium Risk)

   If the branch name contains shell metacharacters (;, $, backticks, etc.), it could cause issues when passed to tmux commands. While git branch names have restrictions, it's good practice to validate or quote:

   # Add validation in step 1:
   # Validate branch name contains only safe characters
   if ! [[ "$BRANCH_NAME" =~ ^[a-zA-Z0-9/_-]+$ ]]; then
       echo "Error: Branch name contains invalid characters"
       exit 1
   fi

   Git does prevent most dangerous characters, but being defensive is wise.

2. Path traversal (Low Risk)

   Using $WORKTREE_DIR/$BRANCH_NAME is safe as long as WORKTREE_DIR is properly set to $REPO_ROOT/.worktrees (which it is in step 1 of the command). No concerns here.

Test Coverage 📋

The test plan in the PR description is comprehensive:

✅ Test inside tmux with pane option
✅ Test inside tmux with window option
✅ Test inside tmux with manual option
✅ Test outside tmux (should skip tmux prompt)

Additional test cases to consider:

1. Branch names with special characters: Test with branches like feature/foo-bar, user-123
2. Very long branch names: Ensure tmux window naming handles this (tmux truncates, but good to verify)
3. Terminal too small for split: What happens if horizontal split fails due to size constraints?
4. Nested tmux sessions: Verify behavior if user is already in a nested tmux setup
5. Rapid succession: Create multiple worktrees quickly to ensure no race conditions with tmux

Documentation 📚

Well done:

• Updated CLAUDE.md to reflect the new tmux auto-launch capability
• Clear step-by-step instructions in the command file
• Good separation between tmux and manual paths

Improvement:

• Consider adding a "Troubleshooting" section to parallel-work.md for common tmux issues:

  ## Troubleshooting
  
  **Tmux pane creation fails:**
  - Ensure terminal window is wide enough for horizontal split (≥160 columns recommended)
  - Check tmux version: `tmux -V` (requires ≥2.0)
  
  **Claude doesn't start in new pane:**
  - Verify claude is in PATH: `which claude`
  - Check `.parallel-context.md` was created in worktree

Additional Observations

1. Consistency with issue Enhancement: Tmux integration for /parallel-work #37: The PR accurately implements "Option 2: AskUserQuestion Choice" from the issue, which is the right call for better UX than command-line flags.

2. Integration point is logical: Adding the tmux logic between steps 6 (write context) and the final output is the right place in the workflow.

3. Backwards compatible: Existing workflows without tmux are unaffected, and the manual option preserves the original behavior.

Recommendations

Must fix before merge:

• Add explicit guidance for quoting paths when substituting placeholders
• Document error handling expectations for tmux command failures

Nice to have:

• Add branch name validation (security hardening)
• Include troubleshooting section in documentation
• Consider more robust tmux availability check

Consider for future PRs:

• Integration with other terminal multiplexers (screen, zellij) could follow this pattern
• Auto-switching to the new pane/window after creation (using tmux select-pane/select-window)

Overall Assessment

This is a high-quality PR that significantly improves the user experience of the /parallel-work command. The implementation is thoughtful, well-documented, and follows established patterns. With minor improvements to error handling and path quoting, this will be production-ready.

Recommendation: Approve with minor revisions suggested above.

Great work on this enhancement! 🎉