Skip to main content

​
Introduction

Forge uses Git worktrees to provide complete isolation for every task attempt. This means each AI agent works in its own separate workspace, eliminating conflicts, race conditions, and the fear of breaking your main codebase.
Think of it this way: Instead of one workspace where everyone fights for control, each task gets its own private sandbox to play in safely.

​
What are Git Worktrees?

Git worktrees allow you to check out multiple branches of the same repository simultaneously in different directories. Unlike traditional branching where you switch contexts in a single workspace, worktrees give you parallel, isolated environments.

​
Traditional Git vs Git Worktrees

# You have ONE working directory
~/my-project/

# Switch branches (context switching)
git checkout feature-a  # Work on feature A
git checkout feature-b  # Oops, lost context of feature A

# Can only work on one branch at a time
# AI agents would conflict with each other
Problem: Context switching, conflicts, can’t run multiple agents simultaneously

​
Why Forge Uses Worktrees

​
The Problem Without Worktrees

Imagine running multiple AI agents on the same codebase: Result: Chaos, file conflicts, unpredictable behavior

​
The Solution With Worktrees

Each task gets its own isolated environment: Result: Safe parallel execution, no conflicts, easy comparison

​
Key Benefits

Complete Isolation

Each attempt runs in its own directory. No risk of agents interfering with each other or your main codebase.

Parallel Execution

Run multiple agents simultaneously. Try Claude and Gemini on the same task at once.

Safe Experimentation

Your main branch stays pristine. Experiment fearlessly knowing you can always discard attempts.

Easy Comparison

Review different approaches side-by-side. See exactly what each agent produced.

​
Automatic Worktree Management

Forge handles all worktree operations automatically. You don’t need to know git worktree commands!

​
What Forge Does For You

1

Task Creation

When you create a task, Forge prepares to create worktrees for attempts:
# You do this
forge task create --title "Add authentication"

# Forge prepares (but doesn't create worktree yet)
# Waits for actual attempt execution
2

Attempt Start

When an agent starts working, Forge creates the worktree:
# You do this
forge task attempt --llm claude

# Forge does this automatically
$ git worktree add .forge/worktrees/task-42-attempt-1 -b task-42-attempt-1
$ cd .forge/worktrees/task-42-attempt-1
$ # Agent works here in isolation
3

Agent Execution

The AI agent works in complete isolation:
Main repo:                      Worktree:
~/my-project/                   .forge/worktrees/task-42-attempt-1/
├── src/                        ├── src/
│   └── app.js (unchanged)      │   └── app.js (modified by agent)
├── tests/                      ├── tests/
│   └── ... (unchanged)         │   └── auth.test.js (new file!)
Your main code is never touched during execution.
4

Review

You review changes in the isolated worktree:
# See what the agent changed
forge task diff 42 1

# Compare multiple attempts
forge task compare 42
5

Merge or Discard

Choose to merge good work or discard bad attempts:
# Merge attempt 1 into main
forge task merge 42 1

# Or discard attempt 2
forge task discard 42 2
6

Cleanup

Forge removes worktrees when done:
# Automatic cleanup after merge/discard
$ git worktree remove .forge/worktrees/task-42-attempt-1

​
Worktree Lifecycle

​
Worktree States

StateDescriptionLocation
PendingTask created, no worktree yetN/A
ActiveAgent working in worktree.forge/worktrees/task-N-attempt-M/
ReviewWork complete, awaiting review.forge/worktrees/task-N-attempt-M/
MergedChanges merged to main, worktree removedDeleted
DiscardedAttempt rejected, worktree removedDeleted

​
Best Practices

​
DO ✅

Forge handles all worktree operations. Don’t create/remove worktrees manually unless you know what you’re doing.
# Good: Let Forge handle it
forge task attempt --llm claude

# Bad: Manual worktree creation
git worktree add .forge/worktrees/my-task
Always check what the agent did before merging:
# Review the diff
forge task diff 42 1

# Then merge if satisfied
forge task merge 42 1
Try different agents on critical features:
# Try Claude
forge task attempt 42 --llm claude

# Try Gemini
forge task attempt 42 --llm gemini

# Compare results
forge task compare 42
Discard failed or unwanted attempts promptly:
# Remove attempt 2 if not needed
forge task discard 42 2

​
DON’T ❌

Don’t manually modify worktree files while an agent is running. Let the agent complete its work first.
Don’t delete .forge/worktrees/ manually. Use forge task discard or forge task merge to properly clean up.
Don’t commit directly in worktrees. Forge manages all git operations. Manual commits can break the workflow.

​
Troubleshooting

​
Worktree Already Exists

Error: worktree '.forge/worktrees/task-42-attempt-1' already exists
Solution: 
# List all worktrees
git worktree list

# Remove the stuck worktree
forge task cleanup 42

# Or manually remove it
git worktree remove .forge/worktrees/task-42-attempt-1

​
Disk Space Issues

Worktrees create full copies of your working directory. For large repos: 
# Check worktree disk usage
du -sh .forge/worktrees/*

# Remove old attempts
forge task cleanup --all

# Configure max concurrent attempts
forge config set max_attempts 3

​
Locked Worktrees

Error: 'task-42-attempt-1' is locked
Solution: 
# Unlock the worktree
git worktree unlock .forge/worktrees/task-42-attempt-1

# Remove it
git worktree remove .forge/worktrees/task-42-attempt-1

​
Advanced: Manual Worktree Operations

You rarely need to do this! Forge handles everything automatically. But if you need manual control:
# Create a worktree manually
git worktree add .forge/worktrees/my-experiment -b feature-xyz

# Work in the worktree
cd .forge/worktrees/my-experiment
# Make changes...

# List all worktrees
git worktree list

# Remove when done
cd ../..
git worktree remove .forge/worktrees/my-experiment

​
Next Steps

Tasks & Attempts

Learn about task lifecycle and attempts

AI Agents

Understand the 8 AI coding agents

Creating Tasks

Start creating tasks with worktree isolation

Troubleshooting

Fix common worktree issues