Skip to main content
Background agents are available in Firebender v0.12.2+
Background agents are the first-ever background coding agents for JetBrains IDEs. They allow you to spawn independent AI agents that work in isolated git worktrees, enabling parallel development workflows while keeping your main project untouched.

​
How It Works

Background agents are designed to be ephemeral and task-focused. Everything happens locally on your machine using git worktrees:
  1. Local Isolation: A new git worktree is created locally with your project’s current state
  2. Task-Focused: Each agent is meant for a single task or feature
  3. Local Execution: The AI agent runs entirely on your local machine in a separate project window
  4. Integration Options: When complete, either create a PR/MR or apply changes directly back to your original branch
  5. Cleanup: Remove the agent once the task is complete
Background agents use git worktrees to create isolated copies of your repository locally. This means changes happen in parallel without affecting your main working directory, and everything stays on your machine.

​
Spawning a Background Agent

To create a background agent:
  1. Type your request in the Firebender chat
  2. Click the background agent button next to the send button
Background Agent Button
  1. The agent will spawn in a new project window and start working immediately

​
Managing Background Agents

​
Agent Registry

You can view all your background agents by clicking the background agents icon in the Firebender header. Background Agent Registry The registry shows Agent name and status (Idle, In Progress, Completed, Error)

​
Agent Status States

  • Idle: Agent is ready to work
  • In Progress: Agent is actively executing tasks
  • Completed: Agent has finished its work
  • Error: Agent encountered an issue
You’ll receive notifications when background agents complete their tasks. Click “View Agent” to see the results.

​
Working with Background Agents

Background agents provide two main actions for integrating your changes: Background Agent Actions

​
Pull Request / Merge Request Creation

  • Create PR/MR: Create a pull request (GitHub) or merge request (GitLab) with AI-generated title and description
  • Update PR/MR: Push new changes to existing pull request or merge request
  • View PR/MR: Open the pull request or merge request in your browser

​
Apply Changes to Original Branch

  • Apply Changes: Merge agent changes directly back to your main project
  • Back to Original Project: Navigate back to your main project window
We support both GitHub and GitLab for pull request and merge request creation.

​
Conflict Resolution

When applying changes back to your original project:
  • 3-way merge: Uses git’s 3-way merge for intelligent conflict resolution
  • Conflict markers: Any conflicts are clearly marked in files
  • Commit window: Opens the commit tool window to review conflicts
  • File navigation: Opens the first conflicted file for easy resolution

​
Authentication Setup

​
GitHub Authentication

Option 1: GitHub CLI (Recommended) 
# Install GitHub CLI
brew install gh
# or visit https://cli.github.com/

# Authenticate
gh auth login
Benefits: Works great with enterprise SSO and 2FA. Option 2: OAuth Authentication Click “Authenticate with OAuth” when prompted to sign in through your browser.

​
GitLab Authentication

For GitLab, you need to set up a personal access token in Firebender settings: GitLab Authentication
  1. Go to Settings → Firebender → API Configuration
  2. Add your GitLab personal access token
  3. The token will be used for merge request creation
Pull request and merge request creation requires authentication with your git hosting provider. Follow the authentication setup for your platform.

​
Configuration

You can configure background agent behavior in your firebender.json file using the backgroundAgent configuration: 
{
  "backgroundAgent": {
    "install": "npm install",
    "start": "npm run dev",
    "copyFiles": [".dev.vars", "node_modules/**"],
    "worktreeWarmupCount": 2
  }
}

​
Configuration Options

  • install: Command to run for installing dependencies when the background agent starts
  • start: Command to run to start the development environment (e.g., dev server, build watch)
  • copyFiles: Array of files to copy from your original project to the background agent worktree
  • worktreeWarmupCount: Number of worktrees to pre-warm for faster background agent spawning (optional)
The copyFiles option is useful for environment files, configuration files, or other assets that aren’t tracked in git but are needed for development. This option follows glob patterns.

​
Include Uncommitted Changes

Control whether background agents include your uncommitted changes:
  1. Go to Settings → Firebender → Editor Settings
  2. Toggle “Background Agent Include Uncommitted Changes”
When enabled, uncommitted changes from your main project are automatically applied to the background agent’s worktree using git patches.

​
Best Practices

​
When to Use Background Agents

Ideal for:
  • Complex refactoring tasks
  • Feature implementation
  • Test creation and iteration
  • Experimental changes
  • Tasks requiring multiple cycles
Better for regular chat:
  • Simple code explanations
  • Quick fixes
  • Single-file changes
  • Code reviews

​
Workflow Recommendations

  1. One task per agent: Create a new background agent for each distinct task or feature
  2. Start from clean state: Commit or stash changes before spawning agents
  3. Review before integrating: Always review changes before applying to original project or creating PRs
  4. Clean up completed agents: Remove agents once you’ve integrated their changes

​
Troubleshooting

​
Common Issues

Agent won’t spawn
  • Ensure your project is a git repository
  • Verify git is properly configured
  • Check that your project directory is accessible
Authentication failures
  • Follow the authentication setup for your git hosting provider
  • For GitHub: Check GitHub CLI installation and authentication
  • For GitLab: Verify your personal access token is correctly set in Firebender settings
  • Verify network connectivity for OAuth flows
Apply changes conflicts
  • Use the commit tool window to resolve conflicts
  • Review conflict markers in opened files
  • Consider creating a PR/MR instead for complex conflicts

​
Getting Help

Join our Discord community for support with background agents or any other Firebender features.

​
Examples

​
Feature Development

Query: "Add user authentication with JWT tokens, including login/logout endpoints and middleware"
→ Creates background agent
→ Implements authentication system
→ Creates pull request with comprehensive description

​
Test Suite Creation

Query: "Create comprehensive unit tests for the UserService class with mocking"
→ Spawns background agent
→ Analyzes UserService implementation  
→ Creates test files with proper mocking
→ Applies changes back to original project

​
Refactoring Tasks

Query: "Refactor the payment processing module to use the Strategy pattern"
→ Creates isolated worktree
→ Implements refactoring safely
→ Generates commit messages for each step
→ Creates PR with before/after explanation
⌘I