Primary navigation

Subagents

Delegate to subagents in ZeroTwo and define your own custom agents

In Work and Code, ZeroTwo can hand parts of a job to subagents that run in parallel and report back, so the main agent merges their results into a single reply. You can also define your own agents as Markdown files.

Availability

Subagents are part of Work and Code tasks, both on your computer and in the cloud. Each subagent makes its own model and tool calls, so a task that fans out spends more credits than a single agent working alone.

Subagents take the same slots as the rest of the team: a task can have 4 agents running at once, counting the main agent, which leaves 3 subagents. A subagent can spawn its own subagents, up to two levels deep. Spawning past the limit fails rather than queuing, so the agent sizes its batches to the free slots.

Why subagent workflows help

Exploration notes, logs and traces pile up in the main chat and push out the decisions that matter. Subagents take that noise somewhere else: the main agent keeps the requirements and the decisions, and a subagent returns only a summary of what it found. They also save time on independent work. Start with read-heavy jobs such as exploring a codebase or reading logs, because parallel writers can overwrite each other.

Core terms

  • Subagent workflow: several agents working in parallel, with results combined by the main agent.
  • Subagent: an agent spawned for one task, named by the main agent with a short lowercase name.
  • Subagent run: the agent's own steps, which you can open from the Subagents list in the task side panel.

Triggering subagent workflows

Ask for it directly: "spawn two agents" or "one agent per module". A good prompt says how to split the work, whether to wait for everyone, and what to return. The agent spawns them without blocking, and each result arrives on its own when the subagent finishes.

Review this branch with parallel subagents for security, test gaps and maintainability, wait for all, then summarize by category.

The agent can also copy part of the conversation into a new subagent, so it does not have to restate the context, but copying costs input tokens on every step.

On the desktop app the agent can additionally start an external CLI agent (ZeroTwo, Claude Code, Grok or Kimi) as a subagent. It does this only when you ask for that provider by name, and the CLI must be installed and signed in on your computer.

Choosing models and reasoning

By default a subagent uses the same model as its parent. The agent can pass a different model or reasoning effort when it spawns one, and you can say which you want in your prompt.

Settings > General > Advanced has two related controls:

  • Max Sub-agent Steps limits the steps of each delegated run.
  • Sub-agent Model Routing lets the agent send hard, medium and easy tasks to models you choose for each difficulty. When it is on, spawn requests are limited to those models.

Reasoning levels depend on the model; see Models.

Managing subagents

The Subagents list in the task side panel shows each agent that is still working, with an "is working" label, indented under the agent that spawned it. Once three agents have finished they collapse into one summary row, and selecting it opens the Subagents viewer tab with every run. Open any run to read its steps and final answer.

Steering and stopping go through the main agent. Ask it to message a subagent, give an idle one a follow-up task, interrupt one, or read a finished agent's full result.

Approvals and permissions

Subagents run under their parent's permission settings. Permission rules and approvals for the task apply to them as well, so choose the preset in the composer, such as Ask for approval, before delegating. A custom agent can narrow what a subagent may do through its tool lists.

Custom agents

Customize > Agents lists the agents ZeroTwo can spawn, from plugins and from your own files. On desktop, put a Markdown file in ~/.zerotwo/agents/ and it appears under your personal agents, where you can switch it off. There is room for up to 100 files of 256 KB each. Spawned agents default to the general type unless the request names an installed agent.

Custom agent file format

A file starts with YAML-style front matter, followed by the agent's instructions as the body.

FieldPurpose
nameThe agent's name (required).
descriptionWhat the agent is for.
modelModel id to use.
effortReasoning effort for that model.
maxTurnsStep limit, from 1 to 100.
toolsTools the agent may use.
disallowedToolsTools the agent must not use.
---
name: reviewer
description: PR reviewer focused on correctness, security, and missing tests.
model: gpt-6-luna
effort: medium
---
Review like an owner; lead with concrete findings.

Keep agents narrow, with one job and instructions that stop drift. A reviewer that only reads, and a separate worker that makes the fix, is a good split.