Fork Terminal Skill

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

• "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

Security Warning: The

--dangerously-*

flags and

-y

(yolo) mode bypass safety prompts. Only use in trusted environments where you understand the risks of unattended AI agent execution.

# Fork with Claude Code
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "claude --model opus --dangerously-skip-permissions"

# Fork with Codex CLI
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "codex --model gpt-5.1-codex-max --dangerously-bypass-approvals-and-sandbox"

# Fork with Gemini CLI
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fork-terminal/tools/fork_terminal.py "gemini --model gemini-3-pro-preview -y"

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

Platform Support

• macOS: Fully supported (AppleScript)
• Windows: Fully supported (cmd.exe)
• Linux: Not yet implemented

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

When to Use Worktree Mode

• 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

• 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

• /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

When to Use Tournament Mode

• 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
  }]
}

1. Read the cookbook:

   cookbook/tournament.md

2. 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

/fork-terminal:status

/fork-terminal:review

/fork-terminal:list

/fork-terminal:remove

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

When to Use Visual Mode

• 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

Ctrl+B D

Ctrl+B [

Ctrl+B z

Ctrl+B o

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"