Agent Teams

Agent Teams

Best practices framework for coordinating multiple Claude Code instances as a team. Includes decision framework, coordination patterns, and pre-built templates accessible via /team.

Should You Use a Team?

Is the task decomposable into 3+ independent subtasks?
  |
  +-- NO --> Single session or subagents (stop here)
  |
  +-- YES
       |
       +-- Can subtasks work on DIFFERENT files?
            |
            +-- NO --> Single session with plan mode
            |
            +-- YES
                 |
                 +-- Will time savings justify ~4x token cost?
                      |
                      +-- NO --> Subagents (parallel, cheaper)
                      |
                      +-- YES --> USE AN AGENT TEAM

Quick Lookup

Teams vs Subagents

Rule of thumb: If workers only need to report results back, use subagents. If workers need to share findings or coordinate, use a team.

Team Size

• NEVER more than 5 teammates. Coordination overhead exceeds gains.
• Aim for 5-6 tasks per teammate.
• Always use Opus for the lead (coordination, reasoning) and Sonnet for workers (execution). This cuts costs significantly.

Coordination Patterns

Start with Leader/Specialist. It is the most reliable and easiest to debug.

For detailed descriptions, diagrams, and failure modes: see references/coordination-patterns.md

File Ownership (CRITICAL)

NEVER let two teammates edit the same file. This is the single most important rule.

Before spawning any team:

1. List ALL files the team will touch
2. Assign each file to exactly ONE teammate
3. Include the ownership map in every teammate's initial prompt
4. If a teammate needs info from another's file, they READ (never write)

GOOD: Teammate A owns src/api/, Teammate B owns src/components/
BAD:  Both teammates modify src/utils.py

Communication Protocol

• Use TaskCreate for task assignments (shared, visible to all)
• Teammates mark completion via TaskUpdate + SendMessage to lead
• Lead monitors via TaskList (NOT constant messaging)
• NEVER broadcast unless truly team-wide emergency
• One broadcast = N messages (costs scale with team size)

Template System

Pre-built team configurations available via /team command:

Using Templates

/team                          List available templates
/team code-review              Start code review team (adapts to project)
/team refactor --dry           Preview without spawning
/team oss-sprint --max-mode    Sprint with all Opus workers
/team create                   Create new template (guided)

Templates auto-adapt to the current project by discovering agents in .claude/agents/ and mapping them to template roles.

--max-mode flag: Override all worker models to Opus for maximum quality. Applies to any template.

OSS Factory templates: The oss-* templates are designed for open-source project workflows. They use GitHub (issues, PRs, branches, Actions) as the persistence layer for session continuity. Setup: /oss setup. Guide: /oss help.

Custom templates: See references/templates/_meta-template.md

DOs

1. Assign file ownership BEFORE spawning - Map every file to one owner
2. Use Opus lead + Sonnet workers - Significant cost savings (use --max-mode for all-Opus when quality matters most)
3. Give specific initial prompts - Include role, owned files, tasks, success criteria
4. Define success criteria per task - "Tests pass" not "looks good"
5. Shutdown teammates when done - Saves tokens, clean state
6. Check for project-specific agents first - Prefer specialized over generic
7. Read GitHub state at sprint start - gh issue list, gh pr list, git branch -a recover context from previous sessions

DONTs

1. Let two teammates write the same file - Guaranteed conflicts
2. Spawn more than 5 teammates - Diminishing returns
3. Use teams for tasks solvable in under 10 minutes - Overhead exceeds benefit
4. Send broadcasts for routine updates - Direct message the lead instead
5. Forget to clean up - Always TeamDelete when finished
6. Expect session resumption - Teams are single-session, experimental (OSS templates use GitHub state for continuity instead)
7. Nest teams - Not supported (one team per session)
8. Run dependent subagents in parallel - If task B needs task A's output, run them sequentially. Parallel subagents polling/waiting wastes tokens.
9. Assume idle teammates are working - Idle may mean silently blocked (content filter, auth failure). If idle 3+ times without output, investigate or respawn.
10. Include secrets in teammate prompts - use placeholder names (e.g., ${{ secrets.API_KEY }}). Tokens go in env vars or settings.json

Known Issues

iTerm2 Pane Cleanup Bug (GitHub #24385)

When using teammateMode: "tmux" with iTerm2, teammate panes may survive after shutdown/TeamDelete. The internal it2 session close call lacks the -f flag, causing silent failure in non-interactive context.

Workaround: Close orphaned panes manually with Cmd+W, or run ~/.claude/scripts/team-cleanup.sh after each team session.

Content Filtering Blocking Teammate Writes

Teammates may hit API-level content filtering (Output blocked by content filtering policy) when writing certain files. This is not a permissions or code issue — it's the safety filter blocking output generation. The teammate appears to be working (stays in_progress, rejects shutdown) but keeps going idle without producing files.

Symptoms: Teammate goes idle repeatedly without creating files. Task stays in_progress. Shutdown requests get rejected with "I'm still working."

Affected content: Code of conduct files, security-related templates, any text discussing sensitive topics.

Workaround: Shut down the stuck teammate and either (a) write the file yourself, (b) spawn a fresh subagent with a rephrased prompt, or (c) write a simpler version of the file.

gh CLI Auth — Use GH_TOKEN, Not OAuth

The gh CLI's default OAuth browser flow (gh auth login) creates tokens (gho_ prefix) that expire and require interactive re-authentication — completely incompatible with long-running agent team sessions.

Solution: Use a Classic PAT (ghp_ prefix) set as GH_TOKEN in ~/.claude/settings.json. This:

• Never expires (or has long expiry you control)
• Never prompts for browser auth
• Is inherited by ALL Claude Code processes including teammates
• Takes absolute precedence over keyring-stored OAuth tokens

Setup: Run /oss setup which guides through creating a Classic PAT with scopes (repo, workflow, read:org, delete_repo, gist) and adding it to settings.json.

Verification: gh auth status should show (GH_TOKEN) — if it shows (keyring) or (oauth), the env var is not loaded. Restart the Claude Code session.

Still required: gh auth setup-git must be run once to configure git's credential helper to use gh (which reads GH_TOKEN).

Limitations

• Experimental feature behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var
• No session resume for in-process teammates
• One team per session
• No nested teams (teammates cannot create sub-teams)
• Lead is fixed for the session lifetime
• Teammates start with lead's permission mode
• Split panes require tmux or iTerm2
• iTerm2 pane cleanup may fail silently (see Known Issues above)

Token Cost Awareness

Detailed cost modeling and optimization: see references/token-economics.md

References

• Coordination patterns deep dive: references/coordination-patterns.md
• Token economics and cost modeling: references/token-economics.md
• Team architect workflow (anti-patterns, checklists): references/team-architect-workflow.md
• Team templates: references/templates/
• Meta-template for custom templates: references/templates/_meta-template.md
• Command: ~/.claude/commands/team/team.md
• Official repo: https://github.com/lucasbrandao4770/claude-agent-teams

Source: lucasbrandao4770/claude-agent-teams — distributed by TomeVault.