Subagents

A subagent is a helper the main agent starts for one focused job: searching a big codebase, reviewing a change, checking a plan. It works in its own context with its own instructions and tools, then hands back a short report. Your main conversation stays small and on topic.

Syntic Code reaches for subagents by itself when a job suits one. You can also request one by name: “use the explore agent to find every place we parse dates”.

Built-in subagents

Built-in names are lower case and cannot be replaced by your own agents.

Make your own

A custom agent is a Markdown file. The frontmatter describes it; the body is its instructions.

---
name: migration-checker
description: Reviews database migrations for locking and rollback problems
tools: Read, Grep, Glob
model: inherit
---
You review SQL migrations. For each file, check whether it locks large
tables, whether it can be rolled back, and whether it is safe to run while
the old code is still deployed. Report problems as a short list with file
and line.

Later rows win when two agents share a name. A file without name is skipped.

The easy way: /agents

/agents opens a manager with two tabs. Running lists the agents working for this session and background runs (Enter opens one). Library lists your custom agents: n creates one with a short wizard (where to save it, name, description, tools, model, instructions), e edits, d deletes, u puts @agent-<name> in your prompt.

syntic agents --list prints the agent definitions from a shell.

Frontmatter keys

CamelCase spellings (maxTurns, permissionMode, maxBudgetUsd) work too, and --agents JSON takes maxBudgetUsd. The main agent sees each custom agent’s description, so write it as “use this when…”. Tool limits are enforced: a tool the agent is not given is refused when it tries to use it.

Use a custom agent

• Ask for it: “have migration-checker look at the new files in db/migrations”.
• Mention it: type @agent-migration-checker in your prompt.
• Run the whole session as it: syntic --agent migration-checker, or "agent": "migration-checker" in project settings.
• Restrict who can start which agent: permission rules like Agent(explore) (rules).

Watch them work

While a subagent works, a live card under its Agent(...) row shows its kind, current activity, time and tokens; when it is done the card folds to one summary line. The agent panel under the footer lists every running agent at a glance. Press ← on an empty prompt (or /tasks) for the full agents view: every running agent with its status, time, tokens, model and effort. Enter opens an agent’s transcript; x x stops a running one. Ctrl+X Ctrl+K stops all background agents. Set "showAgentsViewByDefault": true to open the view automatically when background agents start. The full key list is on The agents view.

Several at once

When the main agent starts several subagents in one step (say, one per package to review), they run in parallel, not one after another, and their reports come back together. A subagent can also be sent off in the background: the main agent carries on and receives the report once the helper is done. /subtask <task> does that for you with a copy of the current conversation.

Reports are checked

A subagent’s report is not taken at its word. When it says it created or edited files, ran commands or got tests passing, the main agent checks those claims against the subagent’s own tool calls, the files on disk and git status, and adds a PASS, PARTIAL or UNVERIFIED verdict to the report. See Automatic checks.

Permissions

A subagent never gets more freedom than the session that started it: its mode is at most as permissive as its parent’s (bypass only comes from bypass), unless the agent definition was written by you or your organization. Tools its rules would refuse are not offered to it at all.

Spend caps

Each subagent’s cost is tracked on its own and shown per agent in /cost. To stop a runaway helper, give it a cap:

When a subagent reaches its cap it stops, and the main agent gets an error that names the cap, what was spent, where the cap is set, and the work done so far. Nested subagents count toward their parent’s spend.

Limits

Teams and workflows

Two ways to run many agents together build on subagents:

• Agent teams: a lead and named teammates that keep running in the background and message each other.
• Workflows: a planned set of subagent steps that run in parallel and feed each other, ending in one report.