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
  • 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: 
{
  "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. 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 (Deprecated)

Deprecated: Use .firebender/rules/*.mdc files instead. See Rules Reference.
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.
{
  "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 the recommended approach, see Rules Reference.

​
commands (Deprecated)

Deprecated: Use .firebender/commands/*.mdc files instead. See Commands Reference.
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
For the recommended approach, see Commands Reference.

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