Skip to main content
Type /agent to create, update, and manage your agents
Agents in Firebender are specialized AI assistants that can be configured with custom behaviors, tools, and models. All agents are unified - they can appear as custom modes in the mode picker and can also be invoked as specialized assistants for specific tasks.

​
Configuration

Agents are configured in your firebender.json file using the agents array: 
{
  "agents": [
    ".firebender/agents/code-reviewer.md",
    "~/firebender-agents/test-writer.md",
    "/absolute/path/to/agent.md"
  ]
}

​
Path Formats

Paths support multiple formats:
  • Relative paths: .firebender/agents/my-agent.md (relative to project root for project config, ~/.firebender for personal config)
  • Home directory: ~/my-agents/agent.md
  • Absolute paths: /path/to/agent.md

​
Scope

Configuration LocationAgent Availability
Project firebender.jsonAvailable in current project only
Personal ~/.firebender/firebender.jsonAvailable across all projects

​
Agent File Format

Each agent is defined in a Markdown file with YAML frontmatter: 
---
name: Code Reviewer
description: Reviews code for best practices and potential issues
color: "#FF5722"
icon: /absolute/path/to/icons/reviewer.svg
tools: read
model: medium
callable: false
---

You are an expert code reviewer. Your role is to:
- Analyze code for bugs, security issues, and performance problems
- Suggest improvements following best practices
- Check for code style consistency
- Identify potential edge cases

Be thorough but constructive in your feedback.

​
Configuration Fields

​
name
string
Display name of the agent. This appears in the mode picker and when the agent is invoked.
​
description
string
Description of the agent’s purpose and when it should be used. Shows in the mode picker.
​
color
string?
Color for the agent mode in hex, rgb, or named color format (e.g., "#FF5722", "rgb(255, 87, 34)", "red").
​
icon
string?
Absolute path to icon image file (svg or png format) to display for this agent.
​
tools
string?
Comma-separated list of tool groups the agent can use. If not specified, all tools are included and no tools are filtered.You can specify:
  • Tool groups: read, edit, execution, other (see Tool Groups below)
  • MCP tools: mcp_servername_toolname (see MCP Tools below)
​
model
string?
Model to use for this agent. You can specify either a size-based alias or a specific model ID.Size-based aliases (recommended):
  • small: Fast, lightweight model for simple tasks (most cost-effective)
  • medium: Balanced performance and capability for most use cases
  • large: Most capable model for complex reasoning and tasks
  • inherit: Use the model selected in the model picker
Specific model IDs: You can also use specific model IDs like claude-sonnet-4-5-20250929, gpt-5.2, or gemini-3-pro-preview, but size-based aliases are recommended as they automatically adapt when new models are released.If not specified, “default” model is picked.
​
callable
boolean?
Whether this agent can be invoked as a subagent by the main AI during conversations.
  • true: Agent appears in “Sub-agents” submenu and can be automatically called by the main agent for specialized tasks
  • false (default): Agent only appears as a custom mode in the mode picker
Use callable: true for: Specialized agents (test writers, database experts, researchers) that should be automatically delegated to based on their description.Defaults to false if not specified.

​
Tool Groups

Tool groups let you grant access to different categories of capabilities for your agents.
GroupWhat the Agent Can Do
readExplore code without making changes
• Read files, search code with grep, find files by pattern
• Navigate code (jump to definitions, find usages)
• Check linter errors and web search for docs
• Search for and use MCP tools
editModify the codebase
• Edit, create, and delete files
• Rename symbols across the entire project
• Apply patches and refactor code safely
executionRun terminal commands
• Execute bash commands (git, npm, docker, etc.)
• Build projects, run tests, install dependencies
• Monitor and kill processes, execute skills
otherInteract with users and manage workflows
• Ask questions to get user input during execution
• Maintain todo lists to track multi-step task progress
The ability to trigger sub-agents is not in any tool group. Only the main agent can call sub-agents.

​
Using Tool Groups

---
name: Code Reviewer
tools: read
---

---
name: Full Developer
tools: read, edit, execution
---
Combine multiple tool groups to give your agents the right level of access for their specific role.

​
MCP Tools

You can also include tools from MCP servers configured in your firebender.json. The format is: 
mcp_{serverName}_{toolName}
Example: If you have a Supabase MCP server configured: 
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.supabase.com/mcp?project_ref=your_project_ref&read_only=true"
      ]
    }
  }
}
You can include specific Supabase tools in your agent: 
---
name: Database Agent
tools: read, mcp_supabase_list_tables, mcp_supabase_execute_sql
---
See the MCP documentation for more details on configuring MCP servers.

​
Examples

​
Read-Only Code Reviewer

---
name: Code Reviewer
description: Reviews code for best practices and potential issues
color: "#FF5722"
tools: read
model: medium
---

You are an expert code reviewer. Analyze code for:
- Bugs and security issues
- Performance problems
- Best practices violations
- Code style consistency
- Potential edge cases

Be thorough but constructive in your feedback.

​
Test Writer Agent

---
name: Test Writer
description: Generates comprehensive test cases
color: "#4CAF50"
tools: read, edit
model: inherit
callable: true
---

You are a test writing specialist. Create comprehensive test suites that:
- Cover edge cases and error conditions
- Follow testing best practices
- Use appropriate testing frameworks
- Include clear assertions and descriptions

---
name: Developer
description: Full-featured development assistant
tools: read, edit, execution, other
model: large
---

You are a senior developer assistant with full access to read, edit, and execute code.

​
Database Query Agent (with MCP)

---
name: Database Agent
description: Query and analyze database schemas
tools: read, mcp_supabase_list_tables, mcp_supabase_execute_sql
model: small
---

You are a database specialist. Help users:
- Understand database schemas
- Write efficient SQL queries
- Analyze query performance
- Suggest schema improvements

​
Live Reload

Agent configurations are automatically reloaded when you save changes to the agent markdown file. The updated configuration takes effect on your next message - no need to restart or create a new chat.

​
Usage

​
Creating Agents

Use the /agents slash command to list existing agents and create new ones:
Agents slash command

​
Using Agents

Agents can be used in two ways:
  1. Mode Selection: Agents appear in the mode picker alongside built-in Auto, Read, and Write modes. Select an agent to activate it, and all your interactions will use that agent’s configuration.
  2. Automatic Delegation: The main agent can automatically delegate tasks to specialized agents based on their descriptions and expertise.
Use Cmd/Ctrl . (e.g., cmd + period) to quickly toggle between different modes and agents.

​
Sub-agents

All agents in Firebender can function as sub-agents through automatic task delegation. When the main agent encounters a task that matches a specialized agent’s expertise, it can delegate that task to the agent, which works independently and returns results.

​
How Sub-agents Work

When used as sub-agents through delegation:
  • Separate Context: Each delegated task runs in its own context window, separate from the main conversation
  • Task-Focused: Sub-agents are invoked for specific tasks based on their description field
  • Independent Execution: Sub-agents work autonomously using their configured tools and system prompt
  • Result Integration: Results are returned to the main agent and integrated into the conversation

​
Delegation vs. Mode Selection

The same agent configuration can be used in both ways:
Use CaseBehaviorContext
Mode SelectionManually select agent as persistent modeUses main conversation context
DelegationAutomatically invoked for matching tasksUses separate context window

​
Configuration for Delegation

The description field is particularly important for delegation, as it helps the main agent determine when to invoke the sub-agent: 
---
name: Test Writer
description: Generates comprehensive test cases for code. Use when user asks to write tests, create test suites, or add test coverage.
tools: read, edit
model: inherit
callable: true
---

You are a test writing specialist...
Write clear, descriptive description fields that explain when the agent should be used. This helps the main agent make better delegation decisions.