Fork Terminal

Fork Terminal Skill

This skill enables forking terminal sessions to new windows using various AI coding tools or raw CLI commands.

Supported Tools

Model Modifiers

• fast: Use lighter/faster models (haiku, codex-mini, flash)
• heavy: Use most capable models (opus, codex-max, gemini-pro)

How to Execute

1. Identify the tool from the user's request
2. Read the appropriate cookbook for execution details
3. Execute fork_terminal(command) using the Python tool

Tool Selection

Match the user's language against these patterns:

• "fork terminal use claude code to..." → Use cookbook/claude-code.md
• "fork terminal use codex to..." → Use cookbook/codex-cli.md
• "fork terminal use gemini to..." → Use cookbook/gemini-cli.md
• "fork terminal run..." → Use cookbook/cli-command.md

Execution Steps

For AI Coding Tools (Claude Code, Codex, Gemini)

1. Read the corresponding cookbook file to get model variables and command format
2. Determine model based on modifier (fast/heavy/default)
3. If the user requests "with summary" or context handoff:
   • Use the template in prompts/fork_summary_user_prompt.md
   • Fill in conversation history summary
   • Include the next user request
4. Execute via: python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "<full_command>"

For Raw CLI Commands

1. Parse the command from the user's request
2. Run <command> --help first to understand options (if needed)
3. Execute via: python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "<command>"

Example Commands

Default (interactive) — no bypass flags:

# Fork with Claude Code (interactive, user reviews each action)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "claude --model opus"

# Fork with Codex CLI (interactive)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "codex exec -m gpt-5.2-codex"

# Fork with Gemini CLI (interactive REPL)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "gemini --model gemini-2.5-pro"

# Fork with raw CLI
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "npm run dev"

Security Warning (opt-in only): The --dangerously-* flags and -y -p (yolo headless) mode bypass safety prompts. Only add them when you explicitly need autonomous/unattended execution in a trusted environment.

Platform Support

• macOS: Fully supported (AppleScript for Warp/Terminal.app; tmux)
• Linux: tmux path supported; window-mode (AppleScript) not available
• Windows: Basic cmd.exe window launch only; tmux and AppleScript paths are macOS/Unix-only

Note: The coordination.py lock file path uses fcntl (Unix-only) and the terminal-window path uses AppleScript. These features do not work on Windows.

Example Triggers

• "Fork terminal use claude code to refactor the auth module"
• "Fork terminal use codex fast to write tests"
• "Fork terminal run npm start"
• "Spawn a new terminal with gemini to analyze this codebase"

Worktree Mode

Worktree mode creates git-isolated workspaces for parallel development. Each worker gets its own branch and worktree directory.

When to Use Worktree Mode

Use worktree mode when:

• You need git isolation between parallel workers
• Working on multiple features simultaneously
• You want to avoid file conflicts between agents

Worktree Trigger Patterns

• "fork terminal in worktree use claude to..." → Worktree + Claude
• "spawn worktree for..." → Create worktree with task
• "spawn 3 worktrees to..." → Multiple workers
• "fork in worktree from develop..." → Specify base branch

How to Execute Worktree Mode

1. Identify worktree mode from trigger patterns above
2. Ask the user which execution mode they prefer using the AskUserQuestion tool:
   • Interactive (default): Claude stays open for follow-up questions
   • Autonomous: Claude runs the task and exits when done
3. Read the cookbook: cookbook/worktree.md
4. Execute spawn_session.py:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/spawn_session.py \
  --task "<task description>" \
  [--branch "<branch-name>"] \
  [--base "<base-branch>"] \
  [--count <1-4>] \
  [--model <opus|haiku>] \
  [--mode <interactive|autonomous>] \
  [--terminal <auto|tmux|window>]

Worktree Examples

# Single worker
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/spawn_session.py \
  --task "implement user authentication"

# Multiple workers
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/spawn_session.py \
  --task "write API tests" \
  --count 3

# From specific base branch
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/spawn_session.py \
  --task "fix bug in login" \
  --base develop \
  --branch "fix/login-bug"

Terminal Detection

Worktree mode automatically detects the terminal environment:

• Inside tmux: Creates new tmux window
• tmux available: Creates new tmux session
• No tmux: Falls back to new terminal window (same as regular fork)

Management Commands

After spawning worktree workers:

• /fork-terminal:list - Show active worktrees and workers
• /fork-terminal:remove --path <path> - Clean up a worktree

Worktree Example Triggers

• "Spawn worktree to implement the search feature"
• "Fork in worktree to refactor the database layer"
• "Spawn 2 worktrees to work on frontend and backend"
• "Fork terminal in worktree from develop to fix the auth bug"

Tournament Mode

Tournament mode spawns multiple AI CLIs (Claude, Gemini, Codex) to compete on the same task in separate worktrees. After all workers complete, the main session reviews solutions and creates a combined branch with the best parts.

When to Use Tournament Mode

Use tournament mode when:

• You want multiple approaches to the same problem
• You want to compare how different AI tools solve a task
• You need the best solution from multiple attempts

Tournament Trigger Patterns

• "tournament mode to implement X" → All CLIs (claude, gemini, codex)
• "tournament with claude and gemini to fix Y" → Claude + Gemini
• "have claude vs codex compete on Z" → Claude + Codex
• "race to solve X" → All CLIs

How to Execute Tournament Mode

1. Identify tournament mode from trigger patterns above
2. Parse CLIs to use: Default is all three, or parse from request
3. Ask the user where to run workers using AskUserQuestion:

{
  "questions": [{
    "question": "Where should the tournament workers run?",
    "header": "Terminal",
    "options": [
      {"label": "tmux (Recommended)", "description": "Background sessions - more reliable, no visible windows"},
      {"label": "Warp/Terminal", "description": "Visible windows - watch workers in real-time"}
    ],
    "multiSelect": false
  }]
}

4. Read the cookbook: cookbook/tournament.md
5. Execute tournament spawning:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/tournament.py spawn \
  --task "<task description>" \
  [--clis claude,gemini,codex] \
  [--base <base-branch>] \
  --terminal <tmux|window>

Tournament Workflow

1. Spawn: Creates worktrees and starts CLI sessions
2. Compete: Workers independently solve the task
3. Complete: Workers write DONE.md when finished
4. Status: User checks progress with /fork-terminal:status
5. Review: User triggers review with /fork-terminal:review
6. Combine: Create combined branch with best parts

Tournament Commands

Tournament Example

# Spawn tournament
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/tournament.py spawn \
  --task "implement user authentication" \
  --clis claude,gemini,codex

# Check status
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/tournament.py status \
  --tournament "<tournament-id>"

# Generate review report
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/tournament_review.py report \
  --tournament "<tournament-id>"

# Create combined branch
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/tournament_review.py combine \
  --tournament "<tournament-id>"

Tournament Example Triggers

• "Tournament mode to implement user authentication"
• "Have claude, gemini, and codex compete on adding caching"
• "Race to solve the performance issue"
• "Tournament with claude and gemini to refactor the API"

Visual Tournament Mode

Visual tournament mode runs multiple AI CLIs side-by-side in tmux split panes so you can watch them all simultaneously. Unlike regular tournament mode (which uses separate worktrees), visual mode runs all CLIs in the current project.

When to Use Visual Mode

Use visual mode when:

• You want to watch all CLIs working in real-time
• You're doing a quick comparison or code review
• You don't need git isolation between workers
• You want a single tmux session with all CLIs visible

Visual Mode Trigger Patterns

• "visual tournament to review X" → All CLIs in split panes
• "watch all clis review the code" → All CLIs visible
• "tmux visual mode with claude and gemini" → Specific CLIs
• "split pane tournament" → All CLIs in split panes

How to Execute Visual Mode

1. Identify visual mode from trigger patterns above
2. Parse CLIs to use: Default is all three, or parse from request
3. Execute visual tournament:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/visual_tournament.py \
  --task "<task or prompt>" \
  [--clis claude,gemini,codex]

Visual Mode Workflow

1. Spawn: Creates tmux session with split panes
2. Watch: All CLIs run simultaneously, visible in panes
3. Output: Each CLI's output saved to ~/.fork-terminal/visual/<id>/<cli>.txt
4. Detach: Use Ctrl+B then D to detach (CLIs continue running)
5. Reattach: Use tmux attach -t <session> to view again

Tmux Controls

Visual Mode Example

# Run all CLIs to review code
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/visual_tournament.py \
  --task "Review this codebase for security issues"

# Run specific CLIs
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/visual_tournament.py \
  --task "Analyze the authentication flow" \
  --clis claude,gemini

# Don't auto-attach (run in background)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/visual_tournament.py \
  --task "Review the API endpoints" \
  --no-attach

Visual Mode Example Triggers

• "Visual tournament to review the authentication code"
• "Watch all CLIs analyze this codebase"
• "Split pane tournament with claude and codex"
• "Show all CLIs running on security review"