Wiki · Features in depth
Subagents
Helpers that get their own brief and return only the result: when they pay off, when they do not, and how to keep an eye on them.
🐝
A subagent is a helper the agent sends off with a clear brief.
It gets its own conversation and its own terminal, works independently, and only its summary
comes back — not every intermediate step. That is why your conversation does not fill up with what
it tried along the way.
When splitting the work pays off
| Good fit | Why |
|---|---|
| A reasoning-heavy job (root-causing a bug, reviewing code, synthesising research) | The subagent gets the whole space to itself and disturbs nobody |
| Work that would flood the main conversation with data | Only the result returns, not hundreds of lines of intermediate output |
| Several independent branches at once | They run in parallel — three investigations instead of three in a row |
| A fresh look without bias | The subagent does not see what you already assumed, so nothing stops it from saying the opposite |
| Poor fit — do it another way | How |
|---|---|
| One tool call or a small file edit | Just ask for it directly; you save time and money |
| Mechanical work with logic between steps | A script — reproducible and exact |
| A job that needs to ask you something | Subagents cannot ask — the main agent does that |
| Work that must keep running after you close the interface | A scheduled job or a background process — see Scheduled tasks (cron) |
What you see in your conversation
| What appears | What it means |
|---|---|
| "I sent three helpers after that." | The main agent keeps working; results arrive as messages |
| A frame with a count and status | In the app and in the terminal you see who is running, for how long and what they did last |
| A way to steer or stop them | When a subagent heads the wrong way, guide it or end it — no need to wait it out |
| The result as a summary | When you need proof too (a file listing, an HTTP code), ask for it explicitly |
A subagent can neither ask you anything nor hire another subagent — nesting has a limit. When a task needs a conversation with a human, it belongs in the main conversation.
Briefing a subagent
Write the brief like a work order: what the goal is, how you will know it is done, and what it should bring back.
❯ Find what three VPS options cost from Czech providers.
❯ For each, give the price in CZK, what it includes and a link. Return nothing else.
❯ Review this code change for bugs.
❯ Return a list of findings: what, where and how it shows up. If there is nothing, say so.
❯ Go through these three sites and compare them.
❯ Give me a table: what they have, what they lack and how they differ.
When you want the answer in a machine-readable shape (a table, a list of items),
you can give the subagent a fixed output shape (output_schema) — handy when a script
processes the result.
How many can run
| Thing | How it works |
|---|---|
| How many at once | Bounded by delegation.max_concurrent_children (10 in our setup) |
| Concurrency | Tasks start together and results arrive as they finish |
| Durability | Subagents live with the conversation that spawned them — they do not survive closing the interface |
| Visibility | /agents in the terminal, the frame above the composer in the app |
Pitfalls from our systems
| What happened | What to do |
|---|---|
| A subagent reported "done" and nothing had changed. Its report is a claim, not evidence | Verify the outcome yourself — a file, a database query, the page's HTTP code. Put the proof into the brief |
| A subagent got stuck on something that needed our decision | It cannot ask. Either give the job to the main agent, or tell the subagent up front how to decide |
| Work was left half-finished when the conversation ended | Subagents are not a durable service. Anything that must outlive the session belongs in a scheduled job or a background process |
| A subagent did visible edits and the result was poor | For things that matter and are visible, the main agent is the better choice — it holds the whole brief. We keep subagents for research and for work that floods context |
| Ten subagents cost more than we expected | Each has its own context, so you pay for each separately. Delegate deliberately, not "just in case, everywhere" |
Ready-made patterns
| Pattern | What it looks like |
|---|---|
| Research several topics at once | "Investigate these three questions in parallel and return five points for each." |
| Code review | The subagent hunts bugs and security risks while the main agent keeps working |
| Comparing options | Each subagent examines one option and returns the same structure, so they can be compared |
| Gather, then decide | Several subagents collect material and the main agent draws the conclusion |
Our tips
| Tip | Why |
|---|---|
| Say exactly what it should return | A shapeless summary is hard to use; "a table: price, what it includes, link" is usable immediately |
| Say how the work will be proven | Then nobody can just claim it is done |
| Give subagents jobs that do not depend on each other | They then really run in parallel instead of waiting |
| Watch work in progress | Stopping a subagent that went the wrong way is cheaper than finishing a bad result |