28. Subagents & swarm#
Rayu can spread work across several agents. In v3 there is one mechanism for that: the swarm. The agent spawns todo-lane workers, each gets its own session with its own model, and results come back as reports.
There is no Orchestrator mode, no /orchestrator, no custom agent files under
~/.rayu/agents/, and no /agent command that drives Codex or Claude Code. What
exists is the swarm tool, plus per-role model configuration.
What a worker is#
A worker is a full Rayu session with:
- Its own todo lane: the tasks it must complete, prepopulated before it starts. The lane is the source of truth; the spawn prompt is only extra context.
- Its own model and effort, chosen by the coordinator or pinned by a profile.
- A parent edge: it reports back to the session that spawned it, and cannot spawn further agents. Swarms are one level deep by construction.
Workers appear in the UI as they start: a live gallery when spawned inline, or terminal windows when spawned visibly.
Spawning a worker by hand#
You do not have to wait for the coordinator to decide. /subagent launches one
directly:
/subagent --type explore find where session files are written
/subagent --model claude-haiku-4-5 --type review check the diff in src/auth
/subagent --continue <session-id> now add the tests| Flag | Meaning |
|---|---|
--type <kind> | A worker type. If a profile of that name exists, that profile's model and effort are used; otherwise the session's swarm default applies, then the coordinator's model |
--model <name> | Pin the worker's model for this run |
--continue <session-id> | Continue an existing worker session instead of starting a new one |
/subagent-model shows or changes the default worker model for this session,
and /subagent-model inherit makes workers use the coordinator's model.
Both /subagent and /subagent-model need a live server connection; in remote
mode they refuse and say so.
Turning swarm on#
[features]
swarm = true # defaultPer session, /swarm toggles it and /swarm status shows the state.
The other way in is effort: /effort swarm sets the session effort to the
swarm sentinel. That does not change the system prompt; it appends "Use swarms
to get things done in parallel." to each user message and runs the root at
[agents] swarm_root_effort (default low).
/swarm on
/effort swarm
refactor the parser: one worker per grammar file, then integrateWhat the agent can do with the swarm tool#
The model calls one tool named swarm, with an action:
| Action | Does |
|---|---|
spawn | Create a worker. Needs a label and either prompt, phase, or both |
message | Send text to a worker, or broadcast with no target |
status | One worker's state |
list | All members of this swarm |
summary | Compact overview of the whole swarm |
plan_status | The shared plan, if one exists |
await_members | Block until workers finish, with a timeout |
stop | Stop a worker. force is required outside your own subtree |
resume | Resume a stopped worker |
retry | Retry a failed worker |
list_models | Model routes a worker could run on |
list_swarms | All swarms on this machine |
Each spawn can carry model or profile, spawn_mode
(inline, headless, visible, auto), tldr, working_dir, and phase.
Per-role models#
Five roles can run on a different model than the coordinator:
| Role | Who it is |
|---|---|
swarm | Spawned workers |
review | End-of-turn automatic review (/autoreview) |
judge | End-of-turn judging (/autojudge) |
memory | The memory extraction sidecar |
ambient | Ambient-mode sessions |
/agents # role picker
/agents swarm # pick a model for workers
/agents review # pick a model for review
/agents swarm inherit # use the coordinator's model
/agents swarm default # clear the override
/agents global swarm <model> # write the default for every sessionSession overrides live in the session record; global writes
~/.rayu/config.toml. The related config keys:
[agents]
swarm_model = "claude-sonnet-4-6" # worker default; unset means inherit
swarm_effort = "low" # worker effort; unset means low
swarm_root_effort = "low" # coordinator effort while in swarm mode
swarm_spawn_mode = "inline" # inline | headless | visible | auto
swarm_gallery_max_pct = 40 # inline gallery height cap (1-90)
swarm_strip_layout = "vertical" # vertical | horizontalAgent profiles#
A profile is a named model plus a note about when to use it. The coordinator reads the list and picks one per worker, so you can express "cheap model for mechanical edits, strong model for design work" once.
/agents profile # list
/agents profile add fast claude-haiku-4-5 --effort low \
"mechanical edits, renames, formatting"
/agents profile add deep claude-opus-4-6 \
"architecture, cross-file refactors, hard debugging"
/agents profile rm fast
/agents global profile add fast claude-haiku-4-5 "mechanical edits"Profiles declared without global belong to the current session. Globally they
live in ~/.rayu/config.toml:
[[agents.profiles]]
name = "fast"
model = "claude-haiku-4-5"
effort = "low"
description = "mechanical edits, renames, formatting"
[[agents.profiles]]
name = "deep"
model = "claude-opus-4-6"
description = "architecture, cross-file refactors, hard debugging"Control how freely the coordinator hands out models:
| Key | Default | Effect |
|---|---|---|
swarm_model_selection | false | Opt in to agent-chosen models, limited to the allowlist |
swarm_model_allowlist | empty | Exact model or route strings the agent may name |
swarm_model_autoselect | true | Let the coordinator pick from the live catalog when no strict allowlist exists |
profile_setup_hint | true | Show the one-time "set up profiles" hint |
With swarm_model_selection = false and no allowlist, the coordinator can only
choose a profile, not a raw model. That is a safe default: an agent cannot
quietly route your work to an expensive model.
Steering a running swarm#
Ask in plain language and the coordinator uses the tool:
- "How is the swarm doing?" →
summaryorlist - "Tell the API worker to stop touching migrations" →
message - "Stop the parser worker" →
stop - "Wait for everything, then integrate" →
await_members
A worker that finishes reports back to its parent. If a mid-tree member leaves, its children are reparented to their grandparent rather than orphaned, so a crash does not strand work.
Worker lifecycle#
| State | Meaning |
|---|---|
spawned | Session created, not ready yet |
ready | Lane received, waiting for work |
running | Executing a task or tool |
blocked | Cannot proceed: dependency, conflict, missing information |
completed | Lane done, waiting for more work |
failed | Unrecoverable error; needs a decision |
stopped | Shut down deliberately |
crashed | Exited without a clean shutdown |
Customising the coordinator's instructions#
The swarm tool's description carries a swarm prompt that teaches the coordinator how to route work. Override it per project or globally:
| File | Scope |
|---|---|
./.rayu/swarm-prompt.md | This project |
~/.rayu/swarm-prompt.md | Every project |
/swarm-prompt opens whichever one applies in your editor. Keep it short and
concrete: which model for which kind of task, which folders are off limits, and
how you want integration done.
When not to use a swarm#
- A task that fits in one file. Coordinating costs more than the work.
- Anything where two agents would edit the same region. Ownership conflicts are real, and the coordinator's job is to prevent them, not to resolve them.
- Work you cannot describe as separate lanes. If the plan is "figure it out as you go", a single session with a todo list is better.
Next#
Next: Hooks →