Fork Terminal

Fork Terminal Skill

Execute multiple AI agents concurrently in separate terminal windows, each with full context and task isolation.

Core Concept

Compute Advantage Equation:

Engineering Output = (# of Parallel Agents) × (Quality of Specs) × (Agent Autonomy)

Forking terminals allows you to multiply your development capacity by running agents in parallel.

Supported Agents

Usage Patterns

Single Fork

"fork terminal use claude code to implement backend API from specs/api-spec.md"

Multiple Parallel Forks

"fork 3 terminals:
 1. Claude Code: Implement database migrations
 2. Gemini: Design and build UI components
 3. Claude Code: Write integration tests"

With Model Override

"fork terminal use claude code with opus model to refactor entire codebase architecture"

Context Handoff

When forking, automatically pass:

• Current project specification (SPEC_TEMPLATE.md)
• Recent conversation (last 5-10 messages)
• Relevant file paths and contents
• Active task from TodoWrite
• Project context from CLAUDE.md

Implementation

Uses fork_terminal.py (if available) or manual terminal spawning:

1. Detect OS (macOS: open, Linux: gnome-terminal or xterm, Windows: cmd)
2. Spawn new terminal window
3. Navigate to project directory
4. Start agent with context file
5. Monitor via logs in temp/logs/fork-{timestamp}.log

Git Worktree Integration

For complete isolation:

# Create isolated environment
git worktree add ../project-feature-x -b feature/x

# Fork into worktree
"fork terminal in worktree ../project-feature-x use claude code to implement feature X"

Each agent works in separate git worktree = zero conflicts.

Monitoring

All forked agents log to:

• temp/logs/fork-{agent}-{timestamp}.log
• Monitored via hooks system (if enabled)
• Aggregated in main session

Best Practices

When to Fork:

• Independent features that can be built in parallel
• Frontend + Backend simultaneous development
• Research while implementation continues
• Testing while new features are being developed

When NOT to Fork:

• Tasks depend on each other sequentially
• Single file needs editing by multiple agents (conflicts)
• Simple tasks that take <5 minutes

Example Workflows

Full-Stack Parallel Development

"I'm building a SaaS dashboard.

Fork 3 terminals:
1. Claude Code: Create Next.js API routes for user management
   - Read: SPEC_TEMPLATE.md section on backend
   - Create: src/app/api/users/route.ts
   - Implement: CRUD operations with Supabase

2. Gemini: Design dashboard UI components
   - Read: SPEC_TEMPLATE.md section on UI requirements
   - Reference: .ai/design.json for design system
   - Create: src/components/Dashboard.tsx

3. Claude Code: Set up database schema and RLS
   - Read: SPEC_TEMPLATE.md database requirements
   - Create: database/migrations/001_initial_schema.sql
   - Enable: RLS on all tables"

Research + Implementation

"fork 2 terminals:
1. Claude Code (research): Research best practices for WebSocket implementation in Next.js 14
   - Use Deep Research skill
   - Save findings to: temp/research/websocket-patterns.md

2. Claude Code (implementation): Continue building REST API
   - Complete all CRUD endpoints
   - Add error handling
   - Write tests"

Experimental Approaches

"fork 2 terminals to try different approaches:
1. Claude Code: Implement feature using LangGraph multi-agent pattern
2. Claude Code: Implement same feature using simple sequential processing

Test both, keep the better one."

Integration with Main Session

Forked agents report back by:

1. Updating shared PROGRESS.md
2. Committing code to feature branches
3. Adding entries to directives/learning.json
4. Logging to temp/logs/

Main session monitors forks and can:

• Check progress via log files
• Review commits via git log
• Aggregate results when forks complete

Remember: Forking is about multiplying your capacity. Use it liberally for parallel work!