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 YAML

Writes 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 Trash

team 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:

team config edit
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 line
  • session names the herdr session and defaults to project; --session overrides it.
  • in_project names the project this team sits in, by the project's display name, while project: keeps meaning the team's own name; project_lead: true beside it marks the team that leads that project — one team per project, and team check refuses a second. The project's record then carries the lead: the agent of the seat this record's leads: true marks as the team's lead, re-resolved on every launch, so a mark that moves in the record moves the record with it.
  • coordinator and operator name seats: the coordinator dispatches work, the operator receives the watch's reports. leads: true on a seat is the same lead, spelled on the seat the way coordinator: names it. assistant: true marks a seat as its entity's assistant — the one seat team send admits 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 with count; 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.signature is the rule check enforces: a template, where it must stand, and which commits are exempt. Commit signatures read Agent: {display} · {role}, pull request bodies **Agent:** {display} · {role}. Without display, the signature reads "model version"; with it, the lab's own spelling. identity.since skips an older history, identity.humans lists commit authors who don't sign, and identity.forbidden adds to the defaults — ^Claude-Session: lines and session links are always refused.
  • seats[*].cli picks the launch profile; claude-code, codex, cursor, antigravity and grok are available, and team doctor says what the others still need. vendor, model and version spell one seat's model. account names the budget account the seat spends when one lab has two; without it, the seat spends its vendor, and changing either is an edit only the owner makes.
  • launch is 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 — and team never rewrites it: team doctor checks its first word there — one fully quoted literal with its quotes removed, the way a shell would run it — and any relative argument. up and add leave 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 as zsh -x ../x is a note); every other relative argument, and a line that quotes or substitutes text, is reported as not checked, never refused. count: 2 makes the numbered names; parked keeps a seat out of idle reports, stopped keeps it out of up.
  • workspace.mode is shared (every seat in the project) or worktree (each task in its own checkout, with path, base and setup). Every seat except a lead starts in the team's lobby — the record's lobby: if it sets one, else the lobby the registry recorded for the session, else <home>/.config/team/lobbies/<entity> if it names entity:, else the machine-global ~/.config/team/lobby. trust lists that lobby's entry — ~/… under the home, absolute otherwise — along with the project root. up and add refuse a seat whose own folder is a protected checkout, and a legacy trust (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:

team config edit
openai:
  kind: subscription
  reserve: 10%
  sources: [check, status_line]
  check: codex-quota

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