Agent Teams¶

Agent teams let you run a set of role-based AI teammates as coordinated in-process workers — each with its own chat session, tool access, and task assignment — driven by a shared task list and a message mailbox. The team definition lives in your mission repo; the bnerd CLI is the runtime.

Roadmap status

Agent teams landed in bnerd CLI as part of roadmap item B7 (phase 1). The TUI team view (:team) is complete; the future SRE-network / distributed-pod phase is on the roadmap but not shipped yet.

Two execution flows¶

bnerd's AI surfaces support two distinct ways to work with multiple agents:

Normal chat with subagents¶

The default chat (:chat / :code / bnerd pa) lets the AI spin up short-lived, read-only subagents (sub_agent, explore_agent, kube_agent) to handle isolated sub-tasks and return a compact summary. These are ephemeral — they run, report back, and terminate. No shared task list, no mailbox, no persistence.

Use this when you need the AI to delegate a quick lookup or exploration step within a single conversation.

Agent teams — persistent, coordinated teammates¶

An agent team is a set of long-lived teammates: each is a full chat session with its own role, tool registry, and history, connected through a shared task list and a message mailbox. The team-lead session (the chat you are talking to) coordinates by routing tasks, responding to teammate messages, and gating phase transitions. Teammates self-claim unblocked tasks, satisfy review gates, and idle until new work arrives.

Use this when a task is large enough to be split across roles — e.g. adding a new API endpoint across the hq API, CLI, and docs simultaneously, or running a structured PR review with both a code-reviewer and a security-reviewer checking the same commit.

	Normal chat + subagents	Agent teams
Teammate lifetime	One task, then terminated	Long-lived; idle between tasks
Coordination	Lead's own chat	Shared task list + mailbox
Task history	Lost after subagent exits	Persisted to `.bnerd/teams/<id>/`
Resume after crash	No	Yes (`bnerd team resume`)
Safety	Lead's session floor	Per-role tool registry + team SafetyMode floor
Entry point	`:chat`, `:code`, `bnerd pa`	`:team <slug>`, `bnerd team run`, MCP

Getting started¶

Make sure your mission repo's orchestrator/teams/ contains a team recipe (see Team recipes).

Run a team headlessly:

bnerd team run pr-review "review PR #142 in cloud/app/hq"

Or launch from the TUI:
```
bnerd x
:team pr-review
```

See The bnerd team CLI for the full command reference, and Safety model for how tools are scoped per role.