> ## 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.

# firebender.json Syntax

> Complete reference for firebender.json configuration options

<Info>
  Type `/help` in the chat to get help with your firebender.json configuration
</Info>

## Configuration Locations

Firebender supports two configuration scopes:

* **Project Config**: `<project root>/firebender.json` - Version-controlled, applies only to the current project
* **Personal Config**: `~/.firebender/firebender.json` - Applies to all projects and not shared with others

**Merge Strategy**: When both configurations exist, settings are combined with the following rules:

* **rules**, **ignore**: Appended together (both apply)
* **mcpServers**: Combined with personal config taking precedence on name collisions
* **mcpEnvFile**: Project config takes precedence if present
* **commands**, **agents**: Kept separate (both sets available)

Relative paths resolve from the project root (project config) or `~/.firebender` (personal config).

## Fields

All high-level fields in the configuration are optional.

### ignore

**Type**: `string[]?`

Array of glob patterns for files that Firebender should not analyze without explicit permission. Follows `.gitignore` syntax.

Firebender respects ignore patterns for:

* **Implicit context**: Files added automatically to chat context
* **Autocomplete**: Code suggestions from ignored files are completely blocked

Firebender ignores patterns when:

* **Explicit mentions**: You manually paste code from an ignored file into chat
* **Direct edits**: You run inline edit commands on ignored files
* **Terminal/MCP tools**: These tools cannot be restricted by ignore patterns

<Tip>Type `/help I want you to ignore these files...` in chat to get AI assistance setting up ignore patterns for your project.</Tip>

#### Pattern Syntax

Use standard `.gitignore` glob pattern syntax:

**Example**:

```json theme={null}
{
  "ignore": [
    "config.json",           // Specific file
    "dist/**",               // Directory and all contents
    "*.log",                 // All files with .log extension
    "**/logs/**",            // logs directory in any location
    "**/.env*",              // Environment files anywhere
    "**/secrets.properties"  // Specific filename in any directory
  ]
}
```

#### Project vs Personal Configuration

**Project Config**: `<project root>/firebender.json`

* Version-controlled and shared with team
* Applies only to the current project

**Personal Config**: `~/.firebender/firebender.json`

* Applies to all projects
* Not shared with others
* Useful for globally excluding sensitive file patterns

**Example personal config**:

```json theme={null}
{
  "ignore": [
    "**/.env",
    "**/.env.*",
    "**/credentials.json",
    "**/*.key",
    "**/*.pem"
  ]
}
```

**Merge behavior**: When both configurations exist, ignore patterns from both project and personal configs are combined (appended together).

#### Best Practices

<Warning>
  Never store production API keys in your local development environment. Ignore patterns provide defense-in-depth but are not foolproof security.
</Warning>

**Recommended patterns to ignore**:

* **Environment files**: `**/.env`, `**/.env.*`
* **Credentials**: `**/credentials.json`, `**/secrets.json`, `**/secrets.properties`
* **Keys**: `**/*.key`, `**/*.pem`, `**/id_rsa`
* **Build artifacts**: `dist/**`, `build/**`, `**/node_modules/**`

For user-facing overview, see [Ignore Files](/multi-agent/global-rules#ignore-files).

### mcpServers

**Type**: `Object<string, ServerConfig>?`

Configure Model Context Protocol (MCP) servers to provide custom tools for Firebender Agent.

#### mcpServers.\{serverName}

* **mcpServers.\{serverName}.command**: `string?` - The command to execute for the MCP server (required if url is not provided)
* **mcpServers.\{serverName}.url**: `string?` - The URL for HTTP-based MCP servers (required if command is not provided)
* **mcpServers.\{serverName}.args**: `string[]?` - Array of arguments to pass to the command
* **mcpServers.\{serverName}.env**: `Object<string, string>?` - Environment variables to set for the MCP server
* **mcpServers.\{serverName}.headers**: `Object<string, string>?` - HTTP headers for URL-based servers
* **mcpServers.\{serverName}.deferLoading**: `boolean?` - Whether to defer loading tools from this server until needed (default: `true`). Keep the default for service integrations (databases, APIs, monitoring). Only set to `false` for orchestration MCPs that modify core agent behavior.

**Example**:

```json theme={null}
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {"BRAVE_API_KEY": "YOUR_API_KEY"}
    },
    "weather": {
      "command": "npx",
      "args": ["-y", "@h1deya/mcp-server-weather"]
    },
    "api-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {"Authorization": "Bearer YOUR_TOKEN"}
    },
    "orchestrator": {
      "command": "npx",
      "args": ["-y", "@mycompany/orchestrator-mcp"],
      "deferLoading": false
    }
  }
}
```

Firebender follows the same syntax as [Model Context Protocol](https://modelcontextprotocol.io/examples#configuring-with-claude).

For details and examples, see [MCP](/context/mcp/overview).

### mcpEnvFile

**Type**: `string?`

Optional path to a file containing environment variables for MCP servers. Can be either a full path or a relative path from the project root.

**Example**:

```json theme={null}
{
  "mcpEnvFile": ".env.mcp"
}
```

### rules (Deprecated)

<Warning>
  **Deprecated**: Use `.firebender/rules/*.mdc` files instead. See [Rules Reference](/api-reference/rules).
</Warning>

**Type**: `(string | RuleConfig)[]?`

Define guidelines for Firebender to follow when generating code. Can contain both global rules (strings) and path-specific rules (objects).

* **rules\[i]**: `string` - A rule that applies to all files
* **rules\[i].filePathMatches**: `string | string[]?` - Optional glob pattern(s) to match file paths for specific rules. Can be a single pattern or an array of patterns.
* **rules\[i].rules**: `string[]` - Array of rules to apply only to matching files
* **rules\[i].rulesPaths**: `string | string[]` - Path(s) to files containing additional rules. Can be either a single path or an array of paths. Paths can be absolute or relative to the project root.

<Accordion title="Legacy Example (click to expand)">
  ```json theme={null}
  {
    "rules": [
      "Follow Material Design 3 guidelines",
      "Use Kotlin coroutines for async operations",
      {
        "filePathMatches": "**/*Test.kt",
        "rules": ["Use Kotest BDD style", "Prefer property-based testing"],
        "rulesPaths": "test-rules.txt"
      },
      {
        "filePathMatches": ["**/*.kt", "**/*.kts"],
        "rulesPaths": ["/absolute/path/to/rules.txt", "relative/path/to/more-rules.txt"]
      }
    ]
  }
  ```
</Accordion>

For the recommended approach, see [Rules Reference](/api-reference/rules).

### commands (Deprecated)

<Warning>
  **Deprecated**: Use `.firebender/commands/*.mdc` files instead. See [Commands Reference](/api-reference/commands).
</Warning>

**Type**: `CommandConfig[]?`

Define custom commands that can be executed through Firebender's interface. Commands are markdown files containing prompts or instructions for the AI.

<Accordion title="Legacy Configuration (click to expand)">
  #### CommandConfig

  * **name**: `string` - The name of the command as it appears in the UI
  * **path**: `string` - Path to the command file. Supports `~` expansion for home directory, absolute paths, and relative paths (relative to project root for project config, `~/.firebender` for personal config)
  * **model**: `string?` - Optional model to use for this command. See [available models](/get-started/models) for valid model IDs.
  * **mode**: `string?` - Optional mode to use for this command

  **Example**:

  ```json theme={null}
  {
    "commands": [
      {
        "name": "create pr",
        "path": "~/firebender-commands/pr-description.md",
        "model": "gpt-4o",
        "mode": "write"
      },
      {
        "name": "add integration test for git diff",
        "path": "./prompts/add-integration-tests.md",
        "mode": "auto"
      },
      {
        "name": "review code",
        "path": "./prompts/code-review.md",
        "model": "claude-3.5-sonnet",
        "mode": "read"
      }
    ]
  }
  ```

  #### model property

  The `model` property lets you pick which AI model is used for a specific command.

  **Predefined values:**

  * `"default"`: Uses the system's default model selection
  * `"quick"`: Uses the fastest available model for quick tasks

  You can also specify any available model by its ID, for example:

  * `"claude-sonnet-4-20250514"`
  * `"gpt-5"`
  * `"gpt-4o"`
  * `"claude-3.5-sonnet"`

  See [available models](/get-started/models) for valid model IDs.

  If `model` is omitted, the command uses the model you currently have selected in chat.

  #### mode property

  The `mode` property lets you choose how Firebender should run the command:

  * `"auto"`: Let Firebender determine the best mode based on context (default)
  * `"read"`: Read-only mode for analysis, reviews, and explanations
  * `"write"`: Agent mode for making code changes and running terminal commands
  * `"composer"`: UI composition mode for creating interfaces

  If `mode` is omitted, the command uses the mode you currently have selected in chat.

  #### Path resolution

  Command file paths resolve from the configuration location:

  * **Project configuration**: Relative paths resolve from the project root
  * **Personal configuration**: Relative paths resolve from `~/.firebender/`

  Supported path formats:

  * Relative paths: `./prompts/command.md`
  * Absolute paths: `/full/path/to/command.md`
  * Home directory expansion: `~/commands/my-command.md`
</Accordion>

For the recommended approach, see [Commands Reference](/api-reference/commands).

### agents

**Type**: `string[]?`

Array of paths to agent configuration files. Agents are specialized AI assistants that can appear as custom modes in the mode picker and can be invoked for specific tasks. Each agent can have specialized behavior, tools, and models.

Paths support `~` expansion for home directory, absolute paths, and relative paths (relative to project root for project config, `~/.firebender` for personal config).

**Example**:

```json theme={null}
{
  "agents": [
    ".firebender/agents/code-reviewer.md",
    "~/firebender-agents/test-writer.md",
    "/absolute/path/to/agent.md"
  ]
}
```

For details and examples, see [Agents](/api-reference/agents).

### worktrees

**Type**: `WorktreesConfig?`

Configure worktree initialization scripts for parallel agents. When agents run in worktree mode, these commands are executed to set up the isolated environment.

#### WorktreesConfig

* **worktrees.setup-worktree**: `string | string[]?` - Commands or script path for all operating systems (fallback)
* **worktrees.setup-worktree-unix**: `string | string[]?` - Commands or script path for macOS/Linux. Takes precedence over `setup-worktree` on Unix systems.
* **worktrees.setup-worktree-windows**: `string | string[]?` - Commands or script path for Windows. Takes precedence over `setup-worktree` on Windows.

Each configuration 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 with command arrays**:

```json theme={null}
{
  "worktrees": {
    "setup-worktree": [
      "npm ci",
      "cp $ROOT_WORKTREE_PATH/.env .env"
    ]
  }
}
```

**Example with script files**:

```json theme={null}
{
  "worktrees": {
    "setup-worktree-unix": "setup-worktree-unix.sh",
    "setup-worktree-windows": "setup-worktree-windows.ps1"
  }
}
```

**Example with OS-specific configurations**:

```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 .env"
    ]
  }
}
```

For details and examples, see [Parallel Agents - Worktree Init](/multi-agent/worktrees#worktree-init).