Skip to main content
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:
ModeBehaviorBest for
ForegroundBlocks until the subagent completes. Returns the result immediately.Sequential tasks where you need the output.
BackgroundReturns 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.
SubagentPurposeWhy it is a subagent
ExploreSearches and analyzes codebasesCodebase exploration generates large intermediate output that would otherwise bloat the main context.
general-purposeHandles complex research and multi-step delegated workSome 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 tasksThe task is single-purpose and repeatable
You want multiple workstreams to run in parallelYou want a quick, reusable action
The task requires specialized expertise across many stepsThe task completes in one shot
You want an independent verification of workYou 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

TypeLocationScope
Project configfirebender.jsonCurrent project only
User config~/.firebender/firebender.jsonAll 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

FieldRequiredDescription
nameNoUnique display name. Defaults to the filename if omitted.
descriptionNoExplains when the subagent should be used. Firebender reads this to decide delegation.
toolsNoComma-separated list of tool groups or MCP tools the subagent can use. If omitted, all tools are available.
modelNoModel to use: small, medium, large, inherit, default, or a specific model ID.
colorNoOptional color used when the agent appears as a custom mode.
iconNoOptional absolute or resolved icon path.
callableNoIf 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.
BenefitTrade-off
Context isolationStartup overhead because each subagent gathers its own context
Parallel executionHigher token usage when multiple contexts run at once
Specialized focusExtra 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