Subagents - Firebender

Subagents are specialized AI assistants that Firebender’s agent can delegate tasks to. Each subagent operates in its own context window, handles specific types of work, and returns its result to the parent agent. Use subagents to break down complex tasks, do work in parallel, and preserve context in the main conversation.

Context isolation

Each subagent has its own context window. Long research or exploration tasks do not consume space in your main conversation.

Parallel execution

Launch multiple subagents simultaneously. Work on different parts of your codebase without waiting for sequential completion.

Specialized expertise

Configure subagents with custom prompts, tool access, and models for domain-specific tasks.

Reusability

Define custom subagents and use them across projects.

How subagents work

When Firebender encounters a complex task, it can launch a subagent automatically. The subagent receives a prompt with the necessary context, works autonomously, and returns a final message with its results. Subagents start with a clean context. The parent agent includes relevant information in the prompt since subagents do not have access to prior conversation history.

Foreground vs background

Subagents run in one of two modes:

Mode	Behavior	Best for
Foreground	Blocks until the subagent completes. Returns the result immediately.	Sequential tasks where you need the output.
Background	Returns immediately. The subagent works independently.	Long-running tasks or parallel workstreams.

Built-in subagents

Firebender includes built-in subagents that handle context-heavy operations automatically.

Subagent	Purpose	Why it is a subagent
`Explore`	Searches and analyzes codebases	Codebase exploration generates large intermediate output that would otherwise bloat the main context.
`general-purpose`	Handles complex research and multi-step delegated work	Some tasks benefit from a separate context window even when they are not pure codebase exploration.

Why these subagents exist

These operations share common traits: they generate noisy intermediate output, benefit from specialized prompts and tools, and can consume significant context. Running them as subagents solves several problems:

Context isolation: intermediate output stays in the subagent. The parent only sees the final summary.
Model flexibility: subagents can use a different model configuration from the parent.
Specialized configuration: each subagent has prompts and tool access tuned for its specific task.
Cost efficiency: isolating token-heavy work in smaller or specialized agents can reduce overall cost.

You do not need to configure the built-in subagents. Firebender uses them automatically when appropriate.

When to use subagents

Use subagents when…	Use skills when…
You need context isolation for long research tasks	The task is single-purpose and repeatable
You want multiple workstreams to run in parallel	You want a quick, reusable action
The task requires specialized expertise across many steps	The task completes in one shot
You want an independent verification of work	You do not need a separate context window

If you find yourself creating a subagent for a simple task like generating a changelog or formatting imports, consider using a skill instead.

Quick start

Firebender automatically uses subagents when appropriate. You can also create a custom subagent by selecting the agent builder in the mode dropdown.

Custom subagents

Define custom subagents to encode specialized knowledge, enforce team standards, or automate repetitive workflows.

Configuration model

In Firebender, agents and subagents use the same configuration system:

All agent files are registered through the agents array in firebender.json
Any agent with callable: true can be invoked as a subagent
The older subagents array is still supported for backwards compatibility, but new configurations should use agents

Project vs user scope

Type	Location	Scope
Project config	`firebender.json`	Current project only
User config	`~/.firebender/firebender.json`	All projects for the current user

Agent files can live anywhere as long as they are listed in the corresponding agents array. Relative paths resolve from the project root for project config, or from ~/.firebender/ for user config.

Example `firebender.json`

{
  "agents": [
    "agents/verifier.md",
    "agents/debugger.md",
    "~/firebender-agents/security-reviewer.md"
  ]
}

File format

Each subagent is a markdown file with YAML frontmatter followed by the prompt:

---
name: security-auditor
description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
tools: read, edit
model: inherit
callable: true
---
You are a security expert auditing code for vulnerabilities.
When invoked:
1. Identify security-sensitive code paths
2. Check for common vulnerabilities
3. Verify secrets are not hardcoded
4. Review input validation and sanitization
Report findings by severity:
- Critical
- High
- Medium

Configuration fields

Field	Required	Description
`name`	No	Unique display name. Defaults to the filename if omitted.
`description`	No	Explains when the subagent should be used. Firebender reads this to decide delegation.
`tools`	No	Comma-separated list of tool groups or MCP tools the subagent can use. If omitted, all tools are available.
`model`	No	Model to use: `small`, `medium`, `large`, `inherit`, `default`, or a specific model ID.
`color`	No	Optional color used when the agent appears as a custom mode.
`icon`	No	Optional absolute or resolved icon path.
`callable`	No	If `true`, the agent can be invoked as a subagent. Defaults to `false`.

Important configuration note

Fields like readonly and background are not part of the agent file schema in Firebender. Instead:

Subagent availability is controlled by callable: true
Tool restrictions are controlled by tools
Background execution is chosen at invocation time by the parent agent

Using subagents

Automatic delegation

Firebender proactively delegates tasks based on:

The task complexity and scope
Custom subagent descriptions in your configuration
Current context and available tools

Include phrases like “use proactively” or “always use for” in your description field to encourage delegation for specific situations.

Explicit invocation

You can also ask Firebender to use a specific subagent by name in natural language:

Use the verifier subagent to confirm the auth flow is complete
Have the debugger subagent investigate this error
Run the security-auditor subagent on the payment module

Parallel execution

Launch multiple subagents concurrently for maximum throughput:

Review the API changes and update the documentation in parallel

Firebender can issue multiple subagent launches in a single step so those workstreams run simultaneously.

Resuming subagents

Subagents can be resumed to continue previous work. Background subagents preserve state while they run, and the parent agent can continue a prior subagent conversation when needed.

Common patterns

Verification agent

A verification agent independently validates whether claimed work was actually completed. This helps catch cases where an implementation is partially done or unverified.

---
name: verifier
description: Validates completed work. Use after tasks are marked done to confirm implementations are functional.
tools: read, execution
model: small
callable: true
---
You are a skeptical validator. Your job is to verify that work claimed as complete actually works.
When invoked:
1. Identify what was claimed to be completed
2. Check that the implementation exists and is functional
3. Run relevant verification steps
4. Look for edge cases that may have been missed
Report:
- What was verified and passed
- What was claimed but incomplete or broken
- Specific issues that still need work

This pattern is useful for:

Validating that features work end-to-end before marking work complete
Catching partially implemented functionality
Ensuring tests really pass, not just that test files exist

Orchestrator pattern

For complex workflows, a parent agent can coordinate multiple specialist subagents in sequence:

Planner analyzes requirements and creates a technical plan
Implementer builds the feature based on the plan
Verifier confirms the implementation matches requirements

Each handoff should include structured output so the next agent has clear context.

Example subagents

Debugger

---
name: debugger
description: Debugging specialist for errors and test failures. Use when encountering issues.
tools: read, edit, execution
callable: true
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture the error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement a minimal fix
5. Verify the solution works
For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
Focus on fixing the underlying issue, not symptoms.

Test runner

---
name: test-runner
description: Test automation expert. Use proactively to run tests and fix failures.
tools: read, edit, execution
callable: true
---
You are a test automation expert.
When you see code changes, proactively run appropriate tests.
If tests fail:
1. Analyze the failure output
2. Identify the root cause
3. Fix the issue while preserving test intent
4. Re-run to verify
Report test results with:
- Number of tests passed or failed
- Summary of any failures
- Changes made to fix issues

Best practices

Write focused subagents: each subagent should have a single, clear responsibility. Avoid generic helper agents.
Invest in descriptions: the description field determines when Firebender delegates to your subagent.
Keep prompts concise: long prompts dilute focus. Be specific and direct.
Add subagents to version control: commit your subagent files so the team benefits.
Start with Firebender-generated agents: let Firebender draft the initial version, then customize it.

Anti-patterns to avoid

Do not create dozens of generic subagents. A large set of vague agents is hard to maintain and gives Firebender poor delegation signals.

Vague descriptions: “Use for general tasks” gives no useful signal. Be specific.
Overly long prompts: a giant prompt usually makes the subagent slower and harder to maintain.
Duplicating commands: if a task is single-purpose and does not need context isolation, use a command or skill instead.
Too many subagents: start with two or three focused subagents and add more only when you have a clear use case.

Managing subagents

Creating subagents

The easiest way to create a subagent is to ask Firebender to create one for you: Create an agent file at agents/security-reviewer.md, add it to the agents array in firebender.json, and make it callable: true. The security-reviewer subagent should check code for common vulnerabilities like injection, XSS, and hardcoded secrets. You can also create subagents manually by adding markdown files and registering them in project or user config.

Viewing subagents

Callable agents appear in the Sub-agents submenu, and non-callable agents appear as custom modes in the mode picker.

Performance and cost

Subagents have trade-offs. Understanding them helps you decide when to use them.

Benefit	Trade-off
Context isolation	Startup overhead because each subagent gathers its own context
Parallel execution	Higher token usage when multiple contexts run at once
Specialized focus	Extra latency for simple tasks

Token and cost considerations

Each subagent consumes tokens independently: running several in parallel increases total usage
Evaluate the overhead: for quick, simple tasks, the main agent is often faster
Subagents can be slower: the benefit is context isolation and specialization, not raw speed

Context isolation

Parallel execution

Specialized expertise

Reusability

​How subagents work

​Foreground vs background

​Built-in subagents

​Why these subagents exist

​When to use subagents

​Quick start

​Custom subagents

​Configuration model

​Project vs user scope

​Example firebender.json

​File format

​Configuration fields

​Important configuration note

​Using subagents

​Automatic delegation

​Explicit invocation

​Parallel execution

​Resuming subagents

​Common patterns

​Verification agent

​Orchestrator pattern

​Example subagents

​Debugger

​Test runner

​Best practices

​Anti-patterns to avoid

​Managing subagents

​Creating subagents

​Viewing subagents

​Performance and cost

​Token and cost considerations

​Related documentation

How subagents work

Foreground vs background

Built-in subagents

Why these subagents exist

When to use subagents

Quick start

Custom subagents

Configuration model

Project vs user scope

Example `firebender.json`

File format

Configuration fields

Important configuration note

Using subagents

Automatic delegation

Explicit invocation

Parallel execution

Resuming subagents

Common patterns

Verification agent

Orchestrator pattern

Example subagents

Debugger

Test runner

Best practices

Anti-patterns to avoid

Managing subagents

Creating subagents

Viewing subagents

Performance and cost

Token and cost considerations

Related documentation