Skip to main content
Type /help in the chat to get help with your firebender.json configuration

​
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
Type /help I want you to ignore these files... in chat to get AI assistance setting up ignore patterns for your project.

​
Pattern Syntax

Use standard .gitignore glob pattern syntax: Example: 
{
  "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: 
{
  "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

Never store production API keys in your local development environment. Ignore patterns provide defense-in-depth but are not foolproof security.
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.

​
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
Example: 
{
  "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"}
    }
  }
}
Firebender follows the same syntax as Model Context Protocol. For details and examples, see MCP.

​
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: 
{
  "mcpEnvFile": ".env.mcp"
}

​
rules

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.
Example: 
{
  "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"]
    }
  ]
}
For details and examples, see Rules for AI.

​
commands

Type: CommandConfig[]? Define custom commands that can be executed through Firebender’s interface. Commands are markdown files containing prompts or instructions for the AI.

​
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 for valid model IDs.
  • mode: string? - Optional mode to use for this command
Example: 
{
  "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 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

​
Command file format

Command files are markdown documents that contain prompts or instructions for the AI. They can include:
  • Natural language instructions
  • Code examples or templates
  • Specific formatting requirements
  • Context about the codebase or project
Example command file (~/firebender-commands/pr-description.md): 
### Create a GitHub Pull Request from any repo state

Create a PR using `gh` and `git` commands. Determine the best PR title and body based on other merged commits.

Make sure non default branch is used (ie. do not push to main).

If changes are uncommitted, then commit them and push.

Use `--no-pager` with git commands because you won't have access to STDIN while the command is still running. Avoiding interactive editors is best practice here.

If the current state of the repo makes it impractical to create a PR, then just plainly state why that is.
For user-facing overview and cookbooks, see 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: 
{
  "agents": [
    ".firebender/agents/code-reviewer.md",
    "~/firebender-agents/test-writer.md",
    "/absolute/path/to/agent.md"
  ]
}
For details and examples, see Agents.