The Parallel Agents 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
- Type your request and start the agent in worktree mode
- Review the code changes and use run configurations to test the application
- Create a PR
Starting an Agent
To start an agent in worktree mode:
- Type your request in the Firebender chat
- 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:
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:
- Click the worktrees icon in the Firebender header
- 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"
]
}
}
{
"worktrees": {
"setup-worktree": [
"python -m venv venv",
"source venv/bin/activate && pip install -r requirements.txt",
"cp $ROOT_WORKTREE_PATH/.env .env"
]
}
}
{
"worktrees": {
"setup-worktree": [
"npm ci",
"cp $ROOT_WORKTREE_PATH/.env .env",
"npm run db:migrate"
]
}
}
{
"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.'"
]
}
}
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!"
$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"
]
}
}
/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, join our Discord community. 
