Skip to main content
Sub-agents are specialized AI agents that handle scoped tasks within your project. The main agent can delegate work to sub-agents, each with their own tools and instructions.

​
Built-in sub-agents

BRICKS Project Desktop includes one built-in sub-agent:
NameDescriptionTools
exploreRead-only codebase search and explorationread_file, glob, grep
Built-in sub-agents cannot be edited or deleted.

​
Managing sub-agents

Click the Sub-Agents button in the sidebar toolbar to open the management panel.

​
Scopes

Sub-agents are organized into two scopes:
  • Global — available across all open projects. Stored in ~/.bricks-project-desktop/agents/.
  • Project — available only within a specific project. Stored in your project’s .bricks/agents/ directory.
Project-scoped agents override global agents with the same name. Custom global agents override built-in agents with the same name.

​
Create a sub-agent

  1. Open the Sub-Agents panel
  2. Select the Global scope
  3. Click New Agent
  4. Edit the agent’s frontmatter and instructions in the editor
  5. Click Save

​
Agent file format

Sub-agents are markdown files with YAML frontmatter: 
---
name: my-agent
description: Describe when to use this agent
thinking_level: low
tools:
  - read_file
  - glob
  - grep
---

You are a specialized agent. Describe your purpose and instructions here.
Frontmatter fields:
FieldRequiredDescription
nameYesUnique identifier for the agent
descriptionNoWhen to use this agent (shown in the agent card)
modelNoAI model override (e.g., anthropic/claude-haiku-4-5-20251001). See model resolution
thinking_levelNoThinking level override (off, minimal, low, medium, high, xhigh). See thinking level resolution
toolsNoList of tools available to the agent
Available tools: read_file, glob, grep

​
Edit a sub-agent

Click the edit button on an agent card to open the editor. Modify the frontmatter or instructions, then click Save.

​
Delete a sub-agent

Click the remove button on an agent card, then click again to confirm. The agent file is permanently deleted.
Changes to agent files on disk are detected automatically. If you edit agent files with an external editor, the panel updates in real time.

​
Model resolution

When a sub-agent runs, its model is resolved in this order:
  1. Agent file model field — if the agent file specifies a model, it is used
  2. Settings default — the default sub-agent model configured in settings
  3. Provider-specific default — a cost-efficient model for the current provider: claude-haiku-4-5-20251001 for Anthropic, gpt-5.4-mini for OpenAI Codex and GitHub Copilot
  4. Session model — the model selected for the current session
This means sub-agents automatically use a cost-efficient model for the active provider, without requiring per-agent configuration.

​
Thinking level resolution

When a sub-agent runs, its thinking level is resolved in this order:
  1. Agent file thinking_level field — if the agent file specifies a thinking level, it is used
  2. Settings default — the default sub-agent thinking level configured in settings
  3. Model-specific fallback — for reasoning models on the OpenAI Responses API, defaults to low