A team of agents,
any vendor, one crew.
A project declares its team in .agents/team.yaml: the seats, the model each one runs, how each agent signs its work, the rules it works under, the folders it may touch.
npm install -g teamOne file declares the team
A project declares its team in .agents/team.yaml: the seats, the model each one runs, how each agent signs its work, the rules it works under, the folders it may touch.
Safe by design
The owner is a terminal outside herdr with no agent process above it: a seat, or a script a seat runs, cannot approve a file or start a team. Nothing writes a vendor config or an AGENTS.md. Launching a Cursor seat, like launching cursor-agent by hand, creates Cursor's own project record under ~/.cursor/projects for that folder; team writes no trust (.workspace-trusted) and no Cursor config.
The watch tells you
Watches the session, reports idle seats and nudges the operator.
One file, a plan, and a reading
Every block below is a tested page of the command reference, shown as it is there.
The file
.agents/team.yaml — the project's whole team
format: 1
project: beacon
coordinator: claude-keeper
operator: claude-keeper
workspace:
mode: shared
seats:
- role: coordinator
name: claude-keeper
label: coordinator
cli: claude-code
vendor: anthropic
model: Claude Opus
version: "5.5"
launch: claude --model claude-opus-5-5
- role: implementer
name: claude-beacon
label: implementer
cli: claude-code
vendor: anthropic
model: Claude Opus
version: "5.5"
launch: claude --model claude-opus-5-5
budgets:
accounts:
openai:
kind: subscription
reserve: 20%
sources: [check, status_line]
check: examples/checks/codex-quotaThe plan
team up --dry-run — what a start would run, and what it would skip
team up --dry-run ; echo "exit $?"
skip claude-keeper: already ready; left as it is
skip claude-beacon: already ready; left as it is
skip claude-qa: stopped in the file; start it with `team add claude-qa`
+ herdr --session beacon workspace create --cwd . --label watchdog --no-focus
+ herdr --session beacon pane run <pane of watchdog> 'team watch --session beacon'
(a desktop notification follows when the watch exits)
dry run: nothing was run
exit 0The reading
team status — the seats, and the repair for each difference
team status ; echo "exit $?"
team beacon, session "beacon"
claude-keeper missing Claude Opus 5.5 -
claude-beacon working Claude Opus 5.5 w1:p1
budgets:
openai session left 40% used 60% resets in 44m - read 2m ago check fresh
openai daily left 70% used 30% resets unknown claude-beacon last seen 40m ago status line (fallback) stale
openai weekly left 5% used 95% resets in 44m claude-beacon changed 2m ago status line (fallback) fresh, inside reserve 20%
difference: claude-keeper is in the file and is not running
repair: team add claude-keeper
1 difference(s)
exit 1The two transcripts come from the team up and team status pages, each of which runs them against its own fixture team; the plan's project holds one more seat, stopped in the file, so the plan skips it.