Git Worktree Sandboxes

Create isolated development environments using git worktrees for safe experimentation

Overview

Forge’s sandbox feature leverages git worktrees to create isolated development environments. This allows you to experiment with changes, test new features, or work on multiple branches simultaneously without affecting your main working directory.

What are Git Worktrees?

Git worktrees allow you to have multiple working directories attached to the same repository. Each worktree:

• Has its own checked-out branch
• Shares the same git history and objects
• Can be modified independently
• Doesn’t affect other worktrees or the main directory

Creating a Sandbox

Using the —sandbox Flag

Create a sandbox when starting Forge:

# Create a sandbox named "experiment"
forge --sandbox experiment

# Create sandbox and specify directory
forge --sandbox feature-test --directory /path/to/work

What Happens

1. Verification
2. Forge checks if you’re in a git repository:
4. Directory Creation
5. The worktree is created in the parent directory of your git repository:
6. parent-directory/
   ├── my-project/          # Original repository
   └── experiment/          # Sandbox worktree
   

7. Branch Handling
8. Forge handles branch creation intelligently:
10. Environment Setup
11. Forge automatically:

Usage Examples

Experiment with Refactoring

# Create a sandbox for refactoring work
forge --sandbox refactor-auth

# Inside Forge, make changes freely
"Refactor the authentication module to use async/await"

# Changes only affect the worktree, not your main branch

Test a Risky Change

# Create sandbox for testing
forge --sandbox test-new-db

# Try out database migration
"Update the database schema to use UUIDs for primary keys"

# If it works, merge back; if not, just delete the worktree

Parallel Development

# Terminal 1: Work on feature A
forge --sandbox feature-a

# Terminal 2: Work on feature B
forge --sandbox feature-b

# Each sandbox is completely independent

Reusing Sandboxes

If a sandbox already exists, Forge will reuse it:

# First time - creates the worktree
forge --sandbox experiment
# Output: Worktree [Created] /path/to/experiment

# Second time - reuses existing worktree
forge --sandbox experiment  
# Output: Worktree [Reused] /path/to/experiment

Sandbox Reuse Check

Forge verifies the directory is a valid git worktree before reusing:

• Checks for .git file (worktree marker)
• Runs git rev-parse --is-inside-work-tree
• Fails if directory exists but isn’t a git worktree

If you see an error, you may need to manually remove the conflicting directory.

Managing Sandboxes

List All Worktrees

cd /path/to/main/repo
git worktree list

Output:

/path/to/main/repo      abc1234 [main]
/path/to/experiment     def5678 [experiment]
/path/to/feature-test   ghi9012 [feature-test]

Remove a Sandbox

# Remove the worktree
git worktree remove experiment

# Or manually delete and prune
rm -rf /path/to/experiment
git worktree prune

Clean Up All Sandboxes

# List worktrees
git worktree list

# Remove each one
git worktree remove <worktree-path>

Advanced Usage

Sandbox with Specific Directory

Combine sandbox with directory flag:

# Create sandbox and work in specific subdirectory
forge --sandbox api-refactor --directory src/api

# Worktree is created, then Forge changes to src/api within it

Working on Existing Branches

Create a sandbox from an existing branch:

# If branch "feature-x" already exists:
forge --sandbox feature-x

# Forge checks out the existing branch in the worktree

Integration with Conversations

Sandboxes work seamlessly with conversation management:

# Start work in sandbox
forge --sandbox experiment "Implement new feature"

# Later, resume the same conversation in the same sandbox
forge --sandbox experiment --conversation <conversation-id>

Common Workflows

Safe Experimentation Workflow

1. Create Sandbox
2. forge --sandbox try-new-approach
   

3. Make Changes
4. # Inside Forge session
   "Try implementing feature X using approach Y"
   "Run tests to verify it works"
   

5. Review Results
6. # In the sandbox worktree
   git diff
   git log
   

7. Merge or Discard
8. If successful:
9. # Commit in sandbox
   git add .
   git commit -m "Implement feature X"
   
   # Switch to main and merge
   cd /path/to/main/repo
   git merge try-new-approach
   

10. If unsuccessful:
11. # Just remove the worktree
    git worktree remove try-new-approach
    

Multi-Feature Development

1. Create Sandboxes for Each Feature
2. forge --sandbox feature-1 "Implement user authentication"
   # In another terminal
   forge --sandbox feature-2 "Add payment processing"
   

3. Work Independently
4. Each terminal works in isolation:
6. Merge When Ready
7. Merge features in any order:
8. cd /path/to/main/repo
   git merge feature-1
   git merge feature-2
   

Troubleshooting

”Not in a git repository”

Ensure you’re starting Forge from within a git repository:

cd /path/to/git/repo
forge --sandbox mysandbox

“Directory exists but is not a git worktree”

A non-worktree directory has the same name:

# Remove the conflicting directory
rm -rf /path/to/parent/mysandbox

# Try again
forge --sandbox mysandbox

“Cannot create worktree in parent directory”

Repository is at filesystem root:

• This is a limitation of the worktree approach
• Move your repository to a non-root location

Worktree Shows as “locked”

# Check worktree status
git worktree list

# Unlock if needed
git worktree unlock <worktree-name>

Best Practices

Naming Conventions

Use descriptive sandbox names:

# Good
forge --sandbox refactor-database
forge --sandbox test-performance
forge --sandbox fix-bug-123

# Avoid
forge --sandbox temp
forge --sandbox test
forge --sandbox x

Clean Up Regularly

Remove unused sandboxes:

# Weekly cleanup
git worktree list
git worktree remove <unused-worktrees>

Commit Before Removing

If the sandbox has valuable work:

# Commit in the sandbox
cd /path/to/sandbox
git add .
git commit -m "Work from sandbox"

# Now safe to remove the worktree
cd /path/to/main/repo
git worktree remove /path/to/sandbox

Use for Isolated Testing

Sandboxes are perfect for:

• Trying new dependencies
• Testing destructive operations
• Experimenting with major refactors
• Working on proof-of-concepts

Important Limitations

• Sandboxes require a git repository
• Parent directory must be writable
• Cannot create sandbox at filesystem root
• Shared git objects mean disk space savings but also shared history
• Uncommitted changes in sandbox are lost if worktree is removed

Integration with Other Features

With Conversation Management

# Start conversation in sandbox
forge --sandbox feature-x "Start working on feature"

# Resume later in same sandbox
forge --sandbox feature-x --conversation-id <id>

With Custom Agents

# Use custom agent in sandbox
forge --sandbox security-review agent security-auditor "Review authentication"

With MCP Servers

MCP servers work normally in sandboxes:

forge --sandbox browser-test "Use the browser MCP server to test the UI"