Teams

A team launches several agents as one unit, each in a named role with its own context window, model, and instructions, cooperating over messages in a shared channel.

A team launches several agents as one unit, each in a named role with its own context window, model, and instructions, cooperating over messages in a shared channel. Define the roles once in agents.toml, then launch the whole set with one name; each member answers to its own role handle. For a one-off pairing, put roles directly in the layout spec with cell:role; a role set earns a named team when it recurs. You compose the roles the way the work splits — the shipped forge team, one split that works really well, pairs a planner, a coder, and a reviewer on one feature.

rimz agents forge -w feat-complex         # planner, coder, reviewer on one feature
rimz message @planner "ship the plan"     # each member answers to its role handle
rimz agents forge --resume                # reopen the newest closed forge team

Why split the work

Every agent works inside one context window, and everything it does fills it: files read, tool output, discussion, dead ends. A filling window costs more per turn and reasons less sharply, so the window is the real budget a long task runs against. And inside the window, attention is the scarcer resource still: a model weighs everything it holds against everything else, and when everything claims importance, nothing receives it.

Subagents are the first tool against that, and a good one. The parent dispatches an explore subagent to locate the relevant code and folds back a summary instead of the whole search; plan subagents draft competing directions in parallel. But a subagent runs one way: the parent spawns it, collects its report, and still carries the whole task in its own window.

A team splits the task itself across independent windows:

Each member keeps its own context and its own attention, the way specialists on a human team do. Each member still uses its own subagents, so a team stacks on that architecture rather than replacing it.
Each member can run a different provider. Model capability is jagged (brilliant at one kind of work, mediocre at the next), the peaks and valleys sit in different places per model, and each model has a comfort zone shaped by its size and training. Matching phases of the work to models lets one model's peak cover another's valley: better results for fewer tokens.
Members talk both ways, over as many rounds as the work needs: a downstream role can ask, push back, and escalate, which a subagent can never do to its parent.

That is what a team manages: which window holds which part of the problem, and what each window's attention is spent on. The split itself is yours to design: two roles or five, one provider or several, whatever shape the work divides into. The rest of this page walks one split that has proven itself.

The forge loop

forge is the team RimZ builds itself with, shipped ready to copy under examples/teams/forge/: three roles that carry one change through plan, code, and review, each role a profile with its own model, effort, and system-prompt file.

@planner (Claude, on Fable) talks with you. It explores the code through subagents, drafts directions, confirms the design choices with you, and writes the plan. Planning is where a deep model earns its price: Fable reads the intention behind a question, holds a large design in view, and writes implementation plans precise enough to execute. On a complex problem that conversation alone fills 200k to 300k tokens, and by hand-off the window holds the whole design history: the exploration, the alternatives weighed, your decisions. That context is exactly what good design calls for, and exactly what execution doesn't need. Asking the same window to also type the code would push it toward 400k to 600k tokens, where every turn gets slower and pricier and a big model's reasoning starts to dull.
@coder (Codex, on Sol, the current GPT 5.6) starts fresh from the plan: a clean window, the exact files to touch, the decisions already made. Sol is fast, cheap, and writes robust code once the details are pinned down, and a precise plan makes its context loading precise too: it pulls in just the code the change touches and implements from there. It verifies the plan against the real code as it goes rather than trusting it.
@reviewer (Claude, on Opus) is a third fresh window. It reads the plan, reviews the full diff blind before opening the coder's report, so its findings form from the code rather than the coder's narrative, then reconciles that report claim by claim.

By the time implementation starts, two windows understand the problem from different sides: the planner's holds the design history, the coder's holds the code as it stands, and each catches what the other misses. So the roles keep talking. The coder hits a choice the plan left open and takes it to the planner, whose full design context makes it the right desk for the call. Coder and reviewer argue findings with file:line evidence, fix or push back, and escalate to the planner when a dispute turns out to be a design call. Three independent windows, each with its own focus, cooperating as one team.

The split reads like it should multiply cost; in practice it divides it. Building RimZ with forge, a complex change that a single Fable window would carry to 400k or 500k tokens and well past $100 lands around $10 of planning, $20 of coding, and $10 of review, and the quality rises as the price falls, because each window spends its whole budget inside its comfort zone.

A RimZ room running forge teams: the coder messages the planner about a gap in the plan, and the planner takes the design call
_{The loop mid-conversation: @coder finds a gap in the plan and messages @planner with evidence; the planner (center pane) verifies and updates the plan.}

Set up forge

From a checkout of this repository, copy the fragment into the agents home and launch it into a worktree:

mkdir -p ~/.agents/teams
cp -r examples/teams/forge ~/.agents/teams/
rimz agents forge -w feat-complex     # the whole team, one isolated worktree

Then hand the task to the planner and let the loop carry it: type into the planner's pane, or message it.

rimz message @planner "add rate limiting to the ingest API"

The planner comes back to you at its design gates; the sidebar lifts the whole team the moment any role needs you (one team, one line of work). The claude and codex CLIs must be on PATH; models, feature flags, and the rest of the install fine print are in the examples README.

Define your own team

A team in agents.toml (or a drop-in fragment like forge's team.toml) is a list of roles, each bound to a configured profile or registered agent kind, with an optional layout using the same row and column operators as inline specs (commas split columns, plus signs tile rows, slashes stack them). A same-named machine profile overrides the kind's implicit base. Its cells name declared roles or roleless cells, while ad-hoc cell:role suffixes stay exclusive to inline specs:

[agents.teams.forge]
leader = "planner"
layout = "planner,coder+reviewer"

[[agents.teams.forge.roles]]
role = "planner"
profile = "claude-planner"
system-prompt-file = "planner.md"
# ... coder and reviewer roles follow the same shape

Launching the team name opens every member in that layout, and each answers to its role handle: @reviewer inside the team's channel, forge.reviewer from anywhere in the workspace. The optional leader names the role that receives a trailing launch prompt; without it, the first declared role leads. rimz agents forge -w feat-x "task" therefore seeds the planner directly, while the rest of the team starts ready for its hand-offs. rimz agents forge.reviewer launches or re-adds that one role with the same identity it has inside the full team.

Start from the forge directory or from scratch: rename the roles, add or drop some, swap the models and prompts — a pair, a trio, or a whole bench of specialists. The role prompts do the heavy lifting: each one states the role's craft, how the roles hand work to each other, and who owns which decision, which is what turns co-launched agents into a team instead of a row of panes. The full config shape, override fields included, is in configuration → agent profiles, commands, and teams.

Relaunch reconciles instead of duplicating

Point any co-launched layout — a named team or an inline multi-agent spec — at an explicit worktree name, and RimZ reads the state first: a live cohort focuses its tab, a closed cohort with work in progress offers to resume it, and a clean merged tree offers to remove it and start fresh.

rimz agents claude:planner,codex:coder -w feat-once focuses the existing pair when the same command runs again.

--resume (alias --continue) forces the resume path, reopening the newest matching set of sessions: by team name and role for a team, or by cell order for an inline spec. Resume takes identity, working directory, and channel from RimZ's durable records, so it stands alone: no prompt, model, or channel flags ride with it.

rimz agents forge --resume         # reopen the newest closed forge team
rimz agents claude,codex --resume  # reopen the newest matching inline pair
rimz agents claude --resume        # resume the freshest closed Claude session

When the place is easier to name than the spec, rimz agents resume '#feat-x' restores the lane's saved team layout and stray agents without requiring the team name. This place-first form converges a partially live team by adding only its closed members; the spec-first --resume form selects a cohort by team or layout.

One team, one line of work

The room treats a team as a single line of work: the sidebar keeps its members as one contiguous block with one derived state, so one member asking for you lifts the whole block (the sidebar guide → Teams read as one).