Skip to main content
A subagent is a second model run with its own context window, its own tool grant and its own task. It reports back in text. The point is that a long, noisy piece of work, reading forty files to answer one question, does not have to spend the main conversation’s context to do it.

​
The built-in roles

Neither can write, and that is structural rather than an instruction they are asked to follow. Their tool set does not contain a write tool. /explore <task> dispatches the explore agent immediately. /plan does not dispatch the plan agent. That name is claimed by plan mode, so the plan agent is reached only when the parent calls dispatch_subagents. code, test and oracle are not seats. Those names stay reserved, so a file in .seri/agents/ cannot take them. Write a file under a new name if you want a similar job.

​
Running one

Two things work. You run it. /explore where does the permission gate live dispatches immediately, with no round trip through the main model to decide whether to. A file-defined agent works the same way. /plan is plan mode, not this path. The model runs it. Each agent’s description is what the model reads when it decides whether to delegate, so “have someone check this before I push” can reach the right agent on its own.

​
Limits that are structural

  • A subagent can never dispatch further subagents. The dispatch tool is not in any child’s tool set, so recursion is unrepresentable rather than forbidden.
  • Three tasks per dispatch. Tasks past the third in one call come back as not-run rows, so the model can re-dispatch the rest deliberately.
  • Twenty-five turns per child. A child does not inherit the session’s much larger --max-turns budget, which would multiply tokens across three concurrent children.
  • A child runs at the parent’s permission mode. Its bash re-enters the same gate you are sitting behind.

​
Writing your own

Drop a Markdown file in .seri/agents/ for this project, or in your profile root for every project. seri picks it up at the next start. No source change, no registration step.
/reviewer grade the diff on this branch then runs it, and the model can reach it too.

​
The frontmatter rules

  • Tool grant precedence. An explicit tools list wins. Otherwise readonly: true gives the read-only set. Otherwise the agent gets every tool seri has.
  • Names. Lowercase letters, digits and -. A file that takes the name of a slash command or of any routable role is skipped with a warning at startup rather than failing the session. That covers the two built-ins, the reserved names code, test and oracle, and archivist, which is a role you cannot dispatch but cannot shadow either.
  • Models. inherit or a concrete catalog id. An id the catalog does not carry warns and inherits the session model rather than failing.
  • Unknown keys are ignored, so frontmatter written for another harness does not break here.
The format is the one Cursor and Claude Code already use, so existing agent files work when you copy them in. seri does not read .cursor/agents/ or .claude/agents/ itself. An agent written for another harness’s toolset auto-loading here is a surprise, not a convenience. Where files live covers project scope against profile scope.