Agent Teams

Agent Teams are saved rosters of local Codex and Claude Code sessions. Use them when the same group of repositories should be launched or reused together, such as a project team, DevOps team, or release validation team.

What A Team Contains

Each team has slots. A slot stores:

• provider
• repository path
• display name
• role and charter
• optional bootstrap prompt
• launch mode and provider options
• enabled or disabled state

Agent Teams do not create a second messaging system. Once agents are launched or reused, use Agent Mail for messages, context requests, and handoffs.

Creating Teams

You can create a team manually, import selected Agent Mail members, or snapshot currently visible Agent Bridge sessions.

From Mail uses Agent Mail participants and copies their current role and charter into slot-specific values. This is a snapshot; editing a team slot does not update existing mail history.

From Bridge uses live Agent Bridge tmux sessions. If multiple sessions are visible for the same repo, Claude Deck keeps each session as a separate slot so the resulting team can have distinct same-repo roles.

Launch Planning

Before launch, Claude Deck computes a plan. The plan checks:

• provider availability
• Agent Mail MCP/hooks readiness
• live Agent Bridge tmux sessions that can be reused
• disabled slots
• provider launch option validity

By default, launch only includes enabled slots and only reuses wakeable sessions observed through Agent Bridge. Connected non-tmux Agent Mail sessions can still communicate, but they are not reliable team launch/reuse targets.

External Local Agents

Local external agents can use the JSON API:

1. GET /api/v1/agent-teams/presets
2. POST /api/v1/agent-teams/presets/{preset_id}/plan-launch
3. inspect items and plan_hash
4. POST /api/v1/agent-teams/presets/{preset_id}/launch

Launch accepts a reviewed confirm_plan_hash, or skip_plan_confirmation: true for explicit single-step local automation. If a plan hash is stale, the API returns 409 with the updated plan.

After a launch, use the External Agent Orchestration Agent Mail API to discover registered participants, send context requests, create handoffs, and poll for answers.