bnerd team — Agent Teams¶
Run and manage agent teams defined in your mission repo.
bnerd team run spawns a coordinator driver — a scripted AI session holding the team's coordination toolset — that creates and routes tasks, spawns and stops teammates, and ends the run itself by calling team_finish. There is no operator-role "lead" the run waits on: a recipe's lead: field is only an optional hint naming which role's persona the driver should adopt (bnerd team describe prints it as coordinator hint:, or (built-in) when the recipe declares none).
See the full Agent Teams guide for concepts, recipes, and the safety model, and The bnerd team CLI for the full command reference including the driver's tool surface and the event stream.
Synopsis¶
Subcommands¶
| Subcommand | Description |
|---|---|
list | List available team recipes (add --runs to also list persisted run dirs) |
describe <slug> | Show a team recipe's members and settings |
run <slug> [prompt] | Spawn a team and drive it headlessly |
status <team-id> | Show a snapshot of a persisted team's state (driver, roster, task counts, lease) |
No resume or cleanup subcommand
team registers exactly these four subcommands. There is no bnerd team resume and no bnerd team cleanup — see The bnerd team CLI → No resume or cleanup subcommand.
Common flags¶
| Flag | Default | Description |
|---|---|---|
--mission-repo <path> | auto-discovered | Path to the mission repo containing orchestrator/teams/ |
list flags¶
| Flag | Default | Description |
|---|---|---|
--runs | off | Also list persisted run directories under the teams root (id, status, updated) after the recipe listing |
status flags¶
status honors the global -o/--output flag (table (default), json, yaml).
run flags¶
| Flag | Default | Description |
|---|---|---|
--prompt <text> | (empty) | Initial prompt for the coordinator driver (alternative to the positional arg) |
--safety <mode> | read-only | Safety floor: read-only, non-destructive, full |
--auto-approve <policy> | never | never, safe, or all — see Auto-approve policy below |
--auto-skip-questions | off | Skip ask_question prompts (required for CI) |
--json-events | off | Reserved — not implemented yet. Accepted and ignored; events print human-readable either way |
Auto-approve policy¶
--auto-approve controls two kinds of pause: tool-use confirmations and task-completion approvals (tasks declared requires_approval: true).
| Policy | Tool confirmations | Task-completion approvals |
|---|---|---|
never (default) | Prompt on stderr/stdin | Prompt on stderr/stdin |
safe | Still prompt | Auto-approved |
all | Auto-approved | Auto-approved |
safe does not auto-approve read-only tool confirms: a confirm event does not yet carry the tool's safety level, so safe cannot tell a read from a write and prompts instead of guessing. For an unattended run use --auto-approve=all together with --safety=read-only (which limits the team to read-only tools in the first place) and --auto-skip-questions.
Agents can never approve their own work
The coordinator driver has no approval-resolution tool in its toolset — no team_task_approve equivalent. A pending completion approval is resolved only by operator policy (this flag) or by the operator's own bnerd_team_task_approve MCP call, never by an agent. This anti-laundering invariant holds regardless of --auto-approve: the flag is an operator decision made at launch time, not a capability handed to the team.
Roster cap¶
A team's roster (always-on members plus anything spawned on demand) is capped by the team.max_members config key (default 6, env BNERD_TEAM_MAX_MEMBERS). A team_spawn_teammate call beyond the cap fails with an error naming the limit — raise team.max_members if a recipe genuinely needs a larger roster.
Examples¶
# List recipes from the auto-discovered mission repo
bnerd team list
# Describe the pr-review recipe
bnerd team describe pr-review
# Run a PR review interactively
bnerd team run pr-review "review PR #142 in cloud/app/hq"
# Run a read-only triage in CI (never blocks on stdin)
bnerd team run inbox-triage "review yesterday's tickets" \
--safety=read-only --auto-approve=all --auto-skip-questions
# Check the state of a persisted team
bnerd team status run-pr-review-20260828-143000-a1b2c3
# ... or as JSON, for scripting
bnerd team status run-pr-review-20260828-143000-a1b2c3 -o json
# List recipes AND persisted run dirs
bnerd team list --runs
Only four subcommands exist today
team registers list, describe, run and status. There is no bnerd team resume and no bnerd team cleanup.
A run that ends without calling team_finish — including a terminal Ctrl-C, which bnerd team run catches and runs through the same bounded exit grace — is recorded as interrupted on disk (see The bnerd team CLI → Exit behavior). A bnerd team run process has no resume path today — the only way forward is to start it again. (A team started from the TUI can be resumed, by reopening its conversation — see AI Assistant → Resuming an interrupted team — but that is a property of the TUI surface, not of this CLI.) Archiving a finished team's state directory is still unbuilt.