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

CTOR includes two built-in sub-agents:
NameDescriptionTools
generalGeneral-purpose agent for research, multi-step edits, commands, and analysisAll built-in tools (except spawn_agent)
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
When no tools list is specified (or set to null), the agent receives all built-in tools except spawn_agent. To restrict tools, list only the ones you need: Commonly used 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.

​
Instructions file

Skills can drive a sub-agent (typically general) with their own bundled instruction files. When spawning an agent, the main agent can pass an optional instructions_file path — a Markdown file whose body is appended to the sub-agent’s system prompt under a Task-Specific Instructions header.

​
How it works

  1. The skill bundles an instruction file (e.g. agents/grader.md) alongside its SKILL.md
  2. The main agent spawns a sub-agent with instructions_file pointing to that file
  3. CTOR strips the file’s frontmatter and appends the body verbatim — no templating or variable substitution
  4. Any input values the instructions reference (e.g. file paths, configuration) are passed by the caller in the task prompt

​
Path resolution

  • Relative paths resolve against the project root
  • Absolute paths must live inside one of these allowed directories:
    • The project directory
    • Project or global skill directories
    • Project or global agent directories
    • Bundled skill directories
Paths outside these directories are rejected for security.

​
Example

A skill that includes an agents/grader.md instruction file: 
my-skill/
├── SKILL.md
├── agents/
│   └── grader.md       # Instructions for the general sub-agent
└── rules/
    └── conventions.md
The grader.md file uses standard agent file format: 
---
name: grader
---

Grade the outputs found in the directory specified in the task.
Compare each output against the expectations provided.
Write a summary report to the outputs directory.
The main agent spawns the general sub-agent with this file, passing concrete values in the task.

​
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, gemini-3.5-flash for Google, minimax-m2.5 for OpenCode Zen, minimax-m2.7 for OpenCode Go
  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