Agent

Command the smartest models to edit and run your code directly

Example: Create end to end tests and iterates off of gradle runs

Modes

Firebender agent can operate in different modes that affect its behavior.

Use Cmd/Ctrl . (e.g. cmd + period) to toggle between the modes quickly.

Auto

A smaller model auto picks the best mode for your request. You can see it’s reasoning:

Read

Cannot modify files, or access the terminal. It has access to:

• web search
• grep search
• file/folder search
• listing files/directories

This restriction allows the agent to be more thoughtful and plan changes better before attempting any implementation.

Write

• Runs terminal commands, modifies files on top of the tools read mode offers.
• This means the AI can modify files directly for you and test those changes on its own.

Extending Agent Modes

You can create custom agent modes by defining agent configurations in your firebender.json file. Agent modes appear in the mode picker alongside the built-in Auto, Read, and Write modes.

You can use the /agents slash command to list existing agents and create new ones:

Configuration

Agent configurations are defined in the agents property of firebender.json:

{
  "agents": [
    ".firebender/agents/code-reviewer.md",
    "~/firebender-agents/test-writer.md"
  ]
}

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: sonnet
---

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

Field	Required	Description
name	Yes	Display name of the agent mode
description	No	Description shown in the mode picker
color	No	Color for the agent mode (hex, rgb, or named color)
icon	No	Absolute path to icon image (svg or png)
tools	No	Comma-separated list of tools the agent can use. Inherits all tools if omitted
model	No	Model to use (sonnet, opus, haiku, or full model name)

Available Tools

Configure your agent with any combination of these tools:

• read_file - Read files from the codebase
• list_dir - List directory contents
• grep_search - Search file contents with regex
• file_search - Fuzzy search for files by path
• delete_file - Delete files
• run_terminal_cmd - Execute terminal commands
• web_search - Search the web
• edit_file - Edit files in the codebase

File Locations

Agent configurations support both project-level and personal configurations:

Type	Location	Scope
Project agents	.firebender/agents/	Available in current project
Personal agents	~/.firebender/agents/	Available across all projects

Path formats in firebender.json:

• Relative paths: ./agents/my-agent.md (relative to project root or ~/.firebender)
• Home directory: ~/my-agents/agent.md
• Absolute paths: /path/to/agent.md

Context Management

@ mentions

You can quickly add files by using @ in the chat box or by hitting the Add context button.

Image support

• Drag and drop images
• Paste images

Terminal

Customizing Agent Terminal

Agent terminals run in the same environment as your regular terminal. For customizing your agent’s terminal experience, check for the FIREBENDER_TERMINAL=true environment variable that is automatically set in all Firebender terminals.

For example, in your ~/.zprofile or ~/.bashrc:

if [[ -n "$FIREBENDER_TERMINAL" ]]; then
# Custom settings for Firebender agent terminals
export PS1="🔥 \W $ "  # Custom prompt for agent terminals
fi

Note: Users with custom zsh setups may have commands in ~/.zshrc or ~/.zprofile that interfere with Firebender being able to read stdin and stdout properly. You can guard around those by checking if it’s NOT a Firebender terminal:

if [[ -z "$FIREBENDER_TERMINAL" ]]; then
# Commands that might interfere with Firebender
# Only run when NOT in a Firebender terminal
fi

Interactive commands

To prevent the agent from running commands that require user input, we supply it with the following environment variables:

• NONINTERACTIVE=1
• CI=1
• DEBIAN_FRONTEND=noninteractive
• TERM=dumb
• PAGER=cat
• LESS=FRX
• MANPAGER=cat
• GIT_TERMINAL_PROMPT=0
• GIT_PAGER=cat
• npm_config_yes=true
• npm_config_fund=false
• npm_config_audit=false
• TF_IN_AUTOMATION=1
• TF_INPUT=0
• EDITOR=true
• VISUAL=true

Related Documentation

• Subagents - Specialized AI assistants for delegated tasks
• Agent Configs Cookbook - Real-world examples of agent configurations
• Commands - Custom AI commands for your workflow