Worktrees

title: ‘Worktrees’ description: ‘Run agents in isolated Git worktrees for parallel development’

The Worktrees feature lets you run multiple agents simultaneously, each in its own isolated, local environment.

Each agent works in its own local worktree, enabling them to write code, run tests, and build your applications without conflicting each other. Firebender automatically manages worktrees for you.

A worktree is a Git feature that creates multiple working directories from a single repository. Each worktree has its own set of files and changes.

Using Worktree Mode

Basic Worktree Usage

1. Type your request and start the agent in worktree mode
2. Review the code changes and use run configurations to test the application
3. Create a PR

Starting an Agent

To start an agent in worktree mode:

1. Type your request in the Firebender chat
2. Select the worktree mode option before sending

Reviewing Changes

When the agent completes its work, you’ll see two options:

• Review: Opens an integrated diff viewer to inspect all changes
• Create PR: Triggers the built-in /pr command to generate a pull request

Review Panel

Clicking Review opens the review interface with IntelliJ’s native diff viewer:

Run Configurations

You can run configurations for the worktree directory directly from the review panel:

Click the play button to build, test, and run the worktree without opening a new IDE window.

Run configurations in the review panel let you validate changes instantly without switching projects.

Viewing Worktrees in the IDE

Active worktrees appear in the commit panel, showing worktree names, changed files, and branch information.

Creating Pull Requests

Click Create PR and the agent will create the pull request for you:

The agent analyzes the changes, writes a comprehensive PR title and description, creates the pull request on your remote repository, and returns the PR link in chat.

Worktree Management

Viewing Worktrees from Git

You can see all worktrees in your repository using the standard Git command:

git worktree list

Example output:

/path/to/project                             15ae12e [main]
/Users/you/.firebender/worktrees/proj/a1b2c  15ae12e [feat-1-a1b2c]
/Users/you/.firebender/worktrees/proj/d3e4f  15ae12e [feat-2-d3e4f]

Cleaning Up Worktrees

To remove a worktree:

1. Click the worktrees icon in the Firebender header
2. Click the trash icon next to the worktree

Worktree Init

You can customize the worktree setup by adding a worktrees property to your firebender.json file in the root of your project.

Configuration Options

The worktrees property is an object that supports three configuration keys:

• setup-worktree-unix: Commands or script path for macOS/Linux. Takes precedence over setup-worktree on Unix systems.
• setup-worktree-windows: Commands or script path for Windows. Takes precedence over setup-worktree on Windows.
• setup-worktree: Generic fallback for all operating systems.

Each key accepts either:

• An array of shell commands: executed sequentially in the worktree
• A string filepath: path to a script file relative to firebender.json

Example Setup Configurations

Using Command Arrays

Node.js project

{
  "worktrees": {
    "setup-worktree": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env"
    ]
  }
}

We do not recommend symlinking dependencies into the worktree, as this can cause issues in the main worktree. Instead, we recommend using fast package managers such as bun, pnpm or uv in the Python ecosystem to install dependencies.

Python project with virtual environment

{
  "worktrees": {
    "setup-worktree": [
      "python -m venv venv",
      "source venv/bin/activate && pip install -r requirements.txt",
      "cp $ROOT_WORKTREE_PATH/.env .env"
    ]
  }
}

Project with database migrations

{
  "worktrees": {
    "setup-worktree": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env",
      "npm run db:migrate"
    ]
  }
}

Build and link dependencies

{
  "worktrees": {
    "setup-worktree": [
      "pnpm install",
      "pnpm run build",
      "cp $ROOT_WORKTREE_PATH/.env.local .env.local"
    ]
  }
}

Using Script Files

For complex setups, you can reference script files instead of inline commands:

{
  "worktrees": {
    "setup-worktree-unix": "setup-worktree-unix.sh",
    "setup-worktree-windows": "setup-worktree-windows.ps1",
    "setup-worktree": [
      "echo 'Using generic fallback. For better support, define OS-specific scripts.'"
    ]
  }
}

Place your scripts relative to your project root (where firebender.json is):

setup-worktree-unix.sh (Unix/macOS):

#!/bin/bash
set -e
# Install dependencies
npm ci
# Copy environment file
cp "$ROOT_WORKTREE_PATH/.env" .env
# Run database migrations
npm run db:migrate
echo "Worktree setup complete!"

setup-worktree-windows.ps1 (Windows):

$ErrorActionPreference = 'Stop'
# Install dependencies
npm ci
# Copy environment file
Copy-Item "$env:ROOT_WORKTREE_PATH\.env" .env
# Run database migrations
npm run db:migrate
Write-Host "Worktree setup complete!"

OS-specific Configurations

You can provide different setup commands for different operating systems:

{
  "worktrees": {
    "setup-worktree-unix": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env",
      "chmod +x scripts/*.sh"
    ],
    "setup-worktree-windows": [
      "npm ci",
      "copy %ROOT_WORKTREE_PATH%\\.env"
    ]
  }
}

Debugging

To debug your worktree setup script, redirect the output to a temporary log file:

{
  "worktrees": {
    "setup-worktree": [
      "npm ci 2>&1 | tee /tmp/worktree-setup.log",
      "cp $ROOT_WORKTREE_PATH/.env .env 2>&1 | tee -a /tmp/worktree-setup.log"
    ]
  }
}

Then check /tmp/worktree-setup.log to see the full output of each command.

Best Practices

When to Use Worktrees

Simple, verifiable tasks

Worktrees excel for straightforward tasks you can easily validate. Bug fixes, writing tests, or fixing failing tests are perfect examples. Use the integrated run configurations to quickly verify the fix works as expected without opening a new project.

Long-running isolated tasks

Major refactors that deserve their own PR work great in worktrees. Examples include:

• Migrating from View-based UI to Jetpack Compose
• Updating to Android 14 with the new permissions model
• Converting a large module from Java to Kotlin
• Migrating build scripts from Groovy to Kotlin DSL

These tasks can take hours or days, and worktrees let the agent work independently while you continue on other work.

Multiple features in parallel

Work on multiple features simultaneously without waiting for agents to complete. This requires some context switching but is powerful for developers who can juggle multiple threads. Start an agent in a worktree for one feature, then continue working on something else in your main project.

Troubleshooting

Common Issues

Worktree creation fails

• Ensure your project is a Git repository
• Verify sufficient disk space
• Check Git configuration and permissions

Changes not appearing in review

• Wait for agent to complete all tasks
• Check agent status in the registry
• Verify worktree branch exists with git worktree list

Getting Help

For worktree-related issues or questions, contact [e-mail].