Sub-agents

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:

Name	Description	Tools
`general`	General-purpose agent for research, multi-step edits, commands, and analysis	All built-in tools (except `spawn_agent`)
`explore`	Read-only codebase search and exploration	`read_file`, `glob`, `grep`

Built-in sub-agents cannot be edited or deleted.

Watch a sub-agent run

When the main agent delegates work, the sub-agent’s tool block reports its progress in the chat. While it runs, the block header shows the current step — the tool name and its target, for example Read File · src/App.tsx. Expand the block to see the full task prompt above a live activity log, one row per sub-agent tool call marked running, done, or failed. The log keeps the 30 most recent calls. When the sub-agent finishes, the header replaces the live status with the total tool-call count, and the activity log stays in the expanded block.

Ultra orchestration

On the experimental Ultra thinking level, the agent delegates on its own initiative: instead of working through a long task serially, it splits the work and runs several sub-agents in parallel, then synthesizes their findings. Sub-agents spawned this way get a longer leash than a normal delegation — they inherit the parent chat’s model, may each be given their own thinking level, and can use the project’s MCP tools. A run is cut off after 30 minutes. While children are running, the input bar shows how many are active, along with each one’s model and thinking level. In Main Chat, orchestration children appear in the sidebar as their own sessions, marked with a ⤷ next to the name.

Concurrency limit

Settings → System → Experimental features → Ultra Parallel Agents caps how many sub-agents one Ultra chat runs at once. The default is 3, and the range is 1–8. Work beyond the cap queues and starts as slots free up.

Run artifacts

Every Ultra sub-agent run is written to .bricks/build/agents/ in your project, so a result survives even when the parent chat is interrupted:

File	Contents
`metadata.json`	The run’s model, thinking level, and task
`transcript.jsonl`	The sub-agent’s messages and tool calls
`result.json`	The full, untruncated result

The chat reports a shortened result and names these paths; the complete output is only on disk. .bricks/build/ is already ignored by git in generated projects, so the artifacts do not show up in your working tree. Nothing clears the directory automatically — delete old runs yourself when it grows. If a result cannot be handed back to a live turn — the parent’s turn failed, or the app restarted — CTOR re-prompts the parent chat with the finished report instead of dropping it.

Managing sub-agents

Open the Plugins panel from the sidebar and switch to the Agents tab. Plugins can also install sub-agents. They appear in the Agents tab alongside your own agents.

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

Open the Agents tab
Select the Global scope
Click New Agent
Edit the agent’s frontmatter and instructions in the editor
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:

Field	Required	Description
`name`	Yes	Unique identifier for the agent
`description`	No	When to use this agent (shown in the agent card)
`model`	No	AI model override (e.g., `anthropic/claude-haiku-4-5-20251001`). See model resolution
`thinking_level`	No	Thinking level override (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). See thinking level resolution
`tools`	No	List 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

The skill bundles an instruction file (e.g. agents/grader.md) alongside its SKILL.md
The main agent spawns a sub-agent with instructions_file pointing to that file
CTOR strips the file’s frontmatter and appends the body verbatim — no templating or variable substitution
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:

Agent file model field — if the agent file specifies a model, it is used
Settings default — the default sub-agent model configured in settings
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
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:

Agent file thinking_level field — if the agent file specifies a thinking level, it is used
Settings default — the default sub-agent thinking level configured in settings
Model-specific fallback — for reasoning models on the OpenAI Responses API, defaults to low

Getting started

Working with projects

Ship your app

Reference

Changelog

Built-in sub-agents

Watch a sub-agent run

Ultra orchestration

Concurrency limit

Run artifacts

Managing sub-agents

Scopes

Create a sub-agent

Agent file format

Edit a sub-agent

Delete a sub-agent

Instructions file

How it works

Path resolution

Example

Model resolution

Thinking level resolution

​Built-in sub-agents

​Watch a sub-agent run

​Ultra orchestration

​Concurrency limit

​Run artifacts

​Managing sub-agents

​Scopes

​Create a sub-agent

​Agent file format

​Edit a sub-agent

​Delete a sub-agent

​Instructions file

​How it works

​Path resolution

​Example

​Model resolution

​Thinking level resolution

Built-in sub-agents

Watch a sub-agent run

Ultra orchestration

Concurrency limit

Run artifacts

Managing sub-agents

Scopes

Create a sub-agent

Agent file format

Edit a sub-agent

Delete a sub-agent

Instructions file

How it works

Path resolution

Example

Model resolution

Thinking level resolution