Team configuration
Since 0.5.5 a team's configuration lives in the registry, one record per team at
~/.config/team/team-config/<team id>.json, keyed by the team ID. team init
creates it, every command reads it, and team config edits it. The
project holds no team file: there is nothing to commit and nothing to keep in sync, and a fresh
clone of the project carries no team. The record is per machine, like the rest of the registry.
team reads one team record per team: the one the registry holds for the project the command
runs in, found from the repository's main checkout, so a run inside a linked worktree reads the
same record. The record holds the team's YAML, read by the library's own parser — maps, lists,
one-line { } and [ ], plain and quoted values, comments; anchors, aliases, merge keys, tags,
block scalars, a second document and duplicate keys are refused, with the line number. The JSON
Schema ships at schema/team.schema.json, and every write is validated against it and the rules
behind it before it is stored. The format is walked below, by example; after it, this page
documents the sections one by one: tasks, seats, delivery_order, grant, delegates,
tempo, and budgets with the format.
Editing with team config
team config get <path> prints one value, team config set <path> <value> writes one,
team config unset <path> removes one, and team config edit opens the whole record as YAML in
$VISUAL (else $EDITOR) and stores it when the editor exits 0 and the text validates. A path is
dotted keys; under a list, a segment names the item by its name or by its index:
team config get seats.lead.model
team config set seats.lead.model Opus
team config set watch.unread_after 15m
team config set tasks.policy.dispatch manual
team config unset seats.lead.label
team config edit # the whole record, as YAMLWrites are the owner's, from a terminal outside herdr; get is any caller's. A write that does
not validate is refused whole, and nothing is stored. A change to an owner section leaves the
approval stale, and the run names what the approval no longer covers. The other editor commands
(team add, team remove, team rename, team tempo, team grant, team delegate) edit the
same record. team config get <path> --json prints the value as JSON. The record itself is a JSON
document in the registry holding the YAML text, its digest and its canonical record; read and write
it through team config, never by hand.
Migrating from team.yaml
Up to 0.5.3 the team lived in .agents/team.yaml in each clone. From 0.5.5 that file is legacy:
only team migrate and team import read it. In
each project, from a terminal outside herdr:
team migrate --dry-run # what it would import and move; writes nothing
team migrate # imports the file, verifies it, moves it to the Trashteam migrate imports the file into the registry, reads it back and compares canonical records,
and only then moves the file to the system Trash, or renames it to .agents/team.yaml.migrated
when no Trash can be reached. It never deletes it. --keep-file imports and leaves the file in
place, unread. The approval stays in force: it is signed over the canonical record, not the file's
text. A project that skips the step is imported by the owner's first team up, which says so.
When a leftover file says something the registry does not, team check and team status name
team import as the repair. The file source (team-config.source: file) and --file are
deprecated and kept for tests and snapshots. See UPGRADE-0.5.5.md.
The sections
The format, by example
A documented subset of YAML, read by the library's own parser: maps, lists, one-line { } and
[ ], plain and quoted values, comments. Anchors, aliases, tags, block scalars, several documents
in one record and duplicate keys are refused, with the line number. The record starts with format: 1.
The package ships the JSON Schema at schema/team.schema.json, and every team config write is validated against it. team config edit shows the record as below.
By example:
format: 1 # the only format this version reads
project: hello
coordinator: coordinator # the seat that dispatches work
operator: coordinator # the seat the watch reports to
identity:
signature:
commits:
position: trailer # last-line | trailer | anywhere
exempt: [merge] # merge commits need no signature
rules: # lines added to every seat's rules at launch. Rules delivered as a launch
# option (claude-code, grok) close with "These are standing rules, not a task.";
# rules typed as a first message (codex, cursor, antigravity) close with
# "These are standing rules, not a task: reply ready and wait for your brief."
- Run the tests your change touches, not the whole suite.
workspace:
mode: shared # shared | worktree: the default for every seat
seats:
- role: coordinator
name: coordinator
cli: cursor # the launch profile
vendor: meridian # the model's maker
model: Meridian # the model's name, without its version
version: "1" # the release alone, quoted
launch: cursor-agent # the model is chosen inside Cursor; no approval flags: the profile adds them
- role: implementer
name: implementer
cli: codex
vendor: openai
account: openai-hello # the seat's account, when one lab has two; absent, its lab
model: GPT Sol
version: "6"
display: GPT-6 Sol # the lab's spelling, for the signature
launch: codex -m gpt-6-sol -c model_reasoning_effort=high
parked: true # running, and not reported while idle
- role: implementer
name: implementer-deepseek
cli: claude-code # DeepSeek's model, run by Claude Code
vendor: deepseek
model: DeepSeek Flash
version: "V4.1"
display: DeepSeek V4.1 Flash
launch: team-deepseek # a launcher on the PATH, holding the account's key and endpoint
model_from: launcher # optional: says outright the launcher picks the model; doctor notes
# it and says what checks the model — here nothing can, Claude Code's
# screen never names DeepSeek's
count: 2 # implementer-deepseek and implementer-deepseek-2
- role: reviewer
name: reviewer
cli: antigravity
vendor: google
model: Gemini
version: "3"
launch: agy
stopped: true # kept in the record; `up` doesn't start it
budgets: # the owner's: reserve or floor per account, marks, freshness
accounts:
openai-hello: # the account implementer spends
kind: subscription
reserve: 10% # refuse a launch on a figure inside it
sources: [status_line] # the figure comes off Codex's status linesessionnames the herdr session and defaults toproject;--sessionoverrides it.in_projectnames the project this team sits in, by the project's display name, whileproject:keeps meaning the team's own name;project_lead: truebeside it marks the team that leads that project — one team per project, andteam checkrefuses a second. The project's record then carries the lead: the agent of the seat this record'sleads: truemarks as the team's lead, re-resolved on every launch, so a mark that moves in the record moves the record with it.coordinatorandoperatorname seats: the coordinator dispatches work, the operator receives the watch's reports.leads: trueon a seat is the same lead, spelled on the seat the waycoordinator:names it.assistant: truemarks a seat as its entity's assistant — the one seatteam sendadmits to its entity's main coordinator, by its place in the chain and never by a role's name. At most one seat of a record carries the mark, and never a seat withcount; the entity's assistant is the first mark found walking its teams in chain order — the entity's own team first, then its other teams by team id, rosters in the order the record writes them — so an entity whose records mark none has no assistant.identity.signatureis the rulecheckenforces: a template, where it must stand, and which commits are exempt. Commit signatures readAgent: {display} · {role}, pull request bodies**Agent:** {display} · {role}. Withoutdisplay, the signature reads "model version"; with it, the lab's own spelling.identity.sinceskips an older history,identity.humanslists commit authors who don't sign, andidentity.forbiddenadds to the defaults —^Claude-Session:lines and session links are always refused.seats[*].clipicks the launch profile;claude-code,codex,cursor,antigravityandgrokare available, andteam doctorsays what the others still need.vendor,modelandversionspell one seat's model.accountnames the budget account the seat spends when one lab has two; without it, the seat spends itsvendor, and changing either is an edit only the owner makes.launchis the plain command, without approval flags: the profile adds them. It runs in the folder the seat starts in — the team's lobby, or the project folder for a lead — andteamnever rewrites it:team doctorchecks its first word there — one fully quoted literal with its quotes removed, the way a shell would run it — and any relative argument.upandaddleave a seat out, saying the same words, when the first word is missing there, or when the first word is a shell (sh,bash,zsh, by name or by path) whose first argument is the script, not an option, and that relative script path resolves from the project root and not from that folder (an option-bearing line such aszsh -x ../xis a note); every other relative argument, and a line that quotes or substitutes text, is reported as not checked, never refused.count: 2makes the numbered names;parkedkeeps a seat out of idle reports,stoppedkeeps it out ofup.workspace.modeisshared(every seat in the project) orworktree(each task in its own checkout, withpath,baseandsetup). Every seat except a lead starts in the team's lobby — the record'slobby:if it sets one, else the lobby the registry recorded for the session, else<home>/.config/team/lobbies/<entity>if it namesentity:, else the machine-global~/.config/team/lobby.trustlists that lobby's entry —~/…under the home, absolute otherwise — along with the project root.upandaddrefuse a seat whose own folder is a protected checkout, and a legacytrust(project-relative patterns, or none) cannot launch until it is rewritten as those absolute paths.
budgets
budgets is the owner's: marks (percent used), how long a figure stays fresh, and each
account's reserve or floor. An account's shared key is informational; team does not act
on it. A seat spends its own account: when the record names one, its vendor
when it doesn't, so one lab's two accounts are two buckets; a pattern names the account it
measures, not the seat's. A check command is resolved to a file and hashed in the record
this machine keeps. A change to that file leaves that account's check unapproved: it is
not run, and the account reads unknown. The rest of the record still runs. watch.quota_marks is still read, with a warning, until you move it to
budgets.marks. A figure first seen on one seat does not count until it changes or a
second seat shows the same number. It goes stale from the moment it last changed, and
the last readings are kept in the team's state file. team status prints
them, one row per account and window, when there is an account or a stored reading.
examples/checks/codex-quota is a check for an openai account. It ships with the package: with a
global install it is at $(npm root -g)/team/examples/checks/codex-quota, and it is
examples/checks/codex-quota
in the repository. It is a Bun script — the check needs Bun on PATH, whatever runs team — and
it uses only built-in file modules, so there is no package to install beside it. Copy it onto
PATH and name that command:
openai:
kind: subscription
reserve: 10%
sources: [check, status_line]
check: codex-quotaMore fields
More fields exist — tools, trust, machine, limits, watch, visibility and
releases — and the comments team init writes name them; validation refuses what it cannot
check, and this build acts on what the commands read.