> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebender.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```bash theme={null}
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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"worktrees": {
"setup-worktree": [
"npm ci",
"cp $ROOT_WORKTREE_PATH/.env .env",
"npm run db:migrate"
]
}
}
```
**Build and link dependencies**
```json theme={null}
{
"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:
```json theme={null}
{
"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):
```bash theme={null}
#!/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):
```powershell theme={null}
$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:
```json theme={null}
{
"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:
```json theme={null}
{
"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 [help@firebender.com](mailto:help@firebender.com).