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_file, grep_search, file_search, list_dir
model: claude-sonnet-4-20250514
---

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
required
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 tools the agent can use. If omitted, the agent inherits all available tools.
​
model
string
Model to use for this agent (e.g., claude-sonnet-4-20250514, gpt-5). See available models for valid model IDs.

​
Available Tools

Configure your agent with any combination of these tools:

​
Core Tools

ToolDescription
read_fileRead files from the codebase
list_dirList directory contents
grep_searchSearch file contents with regex patterns
file_searchFuzzy search for files by path
delete_fileDelete files
run_terminal_cmdExecute terminal commands
web_searchSearch the web for information
edit_fileEdit files in the codebase

​
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: 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_file, grep_search, file_search, list_dir
model: claude-sonnet-4-20250514
---

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_file, edit_file, list_dir, grep_search
model: claude-sonnet-4-20250514
---

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

​
Database Query Agent (with MCP)

---
name: Database Agent
description: Query and analyze database schemas
tools: mcp_supabase_list_tables, mcp_supabase_execute_sql, read_file
model: claude-sonnet-4-20250514
---

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

​
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_file, edit_file, list_dir, grep_search
model: claude-sonnet-4-20250514
---

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.