Subagents & swarm
Guides

Subagents & swarm

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:

bash
/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
FlagMeaning
--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#

toml
[features]
swarm = true      # default

Per 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).

bash
/swarm on
/effort swarm
refactor the parser: one worker per grammar file, then integrate

What the agent can do with the swarm tool#

The model calls one tool named swarm, with an action:

ActionDoes
spawnCreate a worker. Needs a label and either prompt, phase, or both
messageSend text to a worker, or broadcast with no target
statusOne worker's state
listAll members of this swarm
summaryCompact overview of the whole swarm
plan_statusThe shared plan, if one exists
await_membersBlock until workers finish, with a timeout
stopStop a worker. force is required outside your own subtree
resumeResume a stopped worker
retryRetry a failed worker
list_modelsModel routes a worker could run on
list_swarmsAll 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:

RoleWho it is
swarmSpawned workers
reviewEnd-of-turn automatic review (/autoreview)
judgeEnd-of-turn judging (/autojudge)
memoryThe memory extraction sidecar
ambientAmbient-mode sessions
bash
/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 session

Session overrides live in the session record; global writes ~/.rayu/config.toml. The related config keys:

toml
[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 | horizontal

Agent 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.

bash
/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:

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:

KeyDefaultEffect
swarm_model_selectionfalseOpt in to agent-chosen models, limited to the allowlist
swarm_model_allowlistemptyExact model or route strings the agent may name
swarm_model_autoselecttrueLet the coordinator pick from the live catalog when no strict allowlist exists
profile_setup_hinttrueShow 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?" → summary or list
  • "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#

StateMeaning
spawnedSession created, not ready yet
readyLane received, waiting for work
runningExecuting a task or tool
blockedCannot proceed: dependency, conflict, missing information
completedLane done, waiting for more work
failedUnrecoverable error; needs a decision
stoppedShut down deliberately
crashedExited 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:

FileScope
./.rayu/swarm-prompt.mdThis project
~/.rayu/swarm-prompt.mdEvery 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 →