Claude Code Complete Guide

Claude Code Agent Teams Beginner Guide: Get Started Fast and Operate Safely

Target Audience

• You're using or just started using Claude Code
• You want to try Agent Teams right away
• You want to start safely with "read-only" tasks before ...

Agent Teams is an experimental feature that coordinates multiple Claude Code sessions as a team, where members can message each other directly. Use cases include parallelizing PR reviews by concern, or investigating unknown bugs with multiple hypotheses simultaneously.

This is an experimental feature

Agent Teams is experimental as of February 2026. Availability and behavior may change depending on your plan, organization settings, and version. This article is based on official documentation at the time of writing.

Key Points

• How to enable Agent Teams as quickly as possible
• How to build your first success with a "read-only review"
• How to prevent runaway agents with CLAUDE.md and permissions
• When to use Subagents vs. Agent Teams
• Known limitations and cost management tips

When to use Agent Teams

Use it when both conditions are met:

1. The task can be parallelized (divisible by concern or hypothesis)
2. Workers benefit from talking to each other (cross-referencing, debating, aligning)

Cases where it's not a good fit:

• Tasks that can be completed solo
• Strong sequential dependencies (A→B→C)
• Multiple agents editing the same files (conflict risk)

Quick-start checklist

1. Install Claude Code
2. Verify installation with a version check
3. Enable Agent Teams
4. Run a "read-only" 3-concern PR review
5. Have the leader clean up the team when done

Each step is explained in the sections below.

Billing and account prerequisites

Claude Code requires authentication via a Claude.ai subscription (Pro / Max) or Claude Console (API).

Usage type	Authentication
Individual	Pro / Max plan via Claude.ai login
Team / Org	Teams / Enterprise account
Direct API	Claude Console (separate billing)

Claude Code and API billing are separate

Claude.ai subscription and Claude API (Console) billing are treated as separate systems. Don't confuse them.

Installation and verification

Install

Follow the official setup instructions. The most common method:

# macOS / Linux / WSL (recommended)
curl -fsSL https://claude.ai/install.sh | bash

Other installation methods

• Homebrew: brew install --cask claude-code (no auto-update)
• Windows PowerShell: irm https://claude.ai/install.ps1 | iex
• WinGet: winget install Anthropic.ClaudeCode (no auto-update)

Verify installation

Confirm the installation actually works:

claude --version

If a version number is displayed, you're ready to proceed.

Enable Agent Teams

Agent Teams is experimental and must be explicitly enabled.

Option A: Environment variable (fastest)

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Option B: settings.json (recommended for reproducibility)

Add it to .claude/settings.json at your project root so the setting applies to the whole team.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

settings.json scope

• ~/.claude/settings.json — applies to all projects for the user
• .claude/settings.json — project-specific (can be committed to Git)

First success: "read-only" PR review

Prompt to use

The key is to explicitly state "no code changes" so agents stick to reading.

Review PR #142.
Concerns: "security", "performance", "testing".
Spawn 3 reviewers in parallel, then have the leader
consolidate and output key findings.
No code changes in this phase (read only).

Claude won't create a team without your confirmation. It proposes the team and waits for approval before proceeding.

In-process mode cheat sheet

In-process mode lets you switch between team members within a single terminal.

Shortcut	Action
Shift + Up / Down	Select / cycle through teammates
Enter	View a teammate's session
Escape	Interrupt the current turn
Ctrl + T	Toggle the task list
Shift + Tab	Switch to delegate mode

Display mode (teammateMode) options

You can set teammateMode in settings.json:

• "auto" (default): split panes if already in tmux, in-process otherwise
• "in-process": switch within a single terminal
• "tmux": tmux split panes for parallel display

CLI flag: --teammate-mode in-process

When done: always clean up

Ask the leader to clean up the team.

Clean up the team.

Cleanup notes

• Always run cleanup from the leader. Running it from a member may leave resources in an inconsistent state.
• If active members remain, they must be shut down first.
• For orphaned tmux sessions: tmux ls then tmux kill-session -t <session-name>

Conversation history is NOT shared with members

An important design assumption: the leader's conversation history is not carried over to members.

Each member receives only:

• Project context (CLAUDE.md, MCP servers, Skills)
• The spawn prompt from the leader

Therefore, your spawn instructions must explicitly include target paths, constraints, and done criteria. Vague instructions lead to poor results.

Minimal CLAUDE.md template

CLAUDE.md is the file that communicates project rules to Claude Code. Each Agent Teams member loads it on spawn.

Minimal template for beginners (copy-paste ready)

# Project Rules (minimal)

## Goal
- Top priorities: safety and reviewability

## Do / Don't
- DO: Document impact scope and done criteria before changes
- DO: Keep changes small and explainable
- DON'T: Read or expose secrets (.env / secrets)
- DON'T: Make destructive changes without explicit instruction

## How to work
- Present a plan and get approval first
- Progress from "read-only review" to "small fixes"

## Paths
- Auth: src/auth/**
- API: src/api/**
- Tests: test/**

Permissions: prevent runaway agents and data leaks

Claude Code manages permissions via the /permissions command.

Rule evaluation order

Permission rules are evaluated in deny → ask → allow order. The first matching rule wins, so deny always takes precedence.

Minimal configuration for beginners

A "deny only the dangerous stuff" approach:

{
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ]
  }
}

Alternative to banning curl: use WebFetch with domain allow-listing

When external access is needed, allowing WebFetch by domain is more scoped than Bash curl:

WebFetch(domain:example.com)

Wildcard behavior

• * — matches a single level
• ** — matches recursively
• Bash(ls *) — space before * enforces word boundary
• Bash(ls*) — no space, no boundary enforcement

Lock the leader to coordination: delegate mode and plan approval

Delegate mode

Prevents the leader from starting implementation work. In delegate mode, the leader can only use coordination tools: spawning, messaging, shutting down teammates, and managing tasks.

Toggle with Shift + Tab.

Plan approval

Requires members to get approval before implementing.

1. Member creates a work plan in read-only plan mode
2. Member sends a plan approval request to the leader
3. Leader approves or rejects with feedback
4. After approval, the member begins implementation

You influence the leader's approval criteria through your prompt (e.g., "only approve plans that include test coverage").

Recommended setup while learning

Use delegate mode + plan approval together. The leader stays focused on coordination, and implementation mistakes are caught before they happen.

Known limitations

Agent Teams is experimental. Be aware of these limitations.

Limitation	Details
/resume and /rewind don't restore members	In-process team members are not restored. Spawn new members after resuming
One team per session	Clean up the current team before creating a new one
No nested teams	Members cannot spawn their own teams or teammates
Leader is fixed	The session that creates the team is always the leader. No transfers or promotions
Split pane environment support	Requires tmux or iTerm2. Not supported in VS Code integrated terminal, Windows Terminal, or Ghostty
Permissions set at spawn	All members start with the leader's permission mode. Individual changes possible after spawn
Shutdown delay	Members finish their current request or tool call before stopping
Task status lag	Members sometimes fail to mark tasks complete, blocking dependent tasks

Cost management

Agent Teams runs an independent context window per member, so token costs scale with team size.

Operational rules for beginners

• Start with 3 members max
• Use broadcast sparingly — cost scales with team size
• Establish a rhythm: progress report → consolidation → shutdown
• Always clean up when done to prevent runaway sessions

Cost-effectiveness guideline

Research, review, and new feature work often justify the extra tokens. Routine tasks are more cost-effective with a single session.

Subagents vs. Agent Teams

Aspect	Subagents	Agent Teams
Context	Own window; results return to caller	Own window; fully independent
Communication	Reports back to main agent only	Members message each other directly
Coordination	Main agent manages everything	Shared task list with self-coordination
Best for	Focused tasks where only the result matters	Work requiring discussion and collaboration
Token cost	Lower (results summarized to main context)	Higher (each member is a separate Claude instance)

Decision criterion: If the answer to "Do workers need to talk to each other?" is yes, lean toward Agent Teams.

Copy-paste prompt collection

A. "Read-only" 3-concern review (recommended)

Review PR #XXX.
Concerns: security / performance / testing. Spawn 3 reviewers in parallel.
Each member reads only. Suggest changes but don't edit files.
Leader consolidates findings as critical / warning / info.

B. Parallel hypothesis testing for unknown bugs

Issue: API intermittently times out.
Split into 3 hypotheses: (1) external API (2) DB locks (3) memory leak.
Each member reports with at least one piece of evidence (logs / files / repro steps).
Leader identifies the most likely hypothesis and one next action.

C. Cleanup (don't forget)

Clean up the team and ensure no member sessions remain.

FAQ

Q. What plan do I need for Agent Teams?

Any plan that supports Claude Code (Pro / Max / Teams / Enterprise / API) should allow you to enable the experimental flag. Availability may vary by plan and organization settings.

Q. Can I use Subagents and Agent Teams together?

Yes. Agent Teams members have the same capabilities as regular Claude Code sessions, so each member can use Subagents internally. However, members cannot create their own teams (no nesting).

Q. Can I change the leader mid-session?

No. The session that creates the team is always the leader. To change the leader, clean up the team and create a new one.

Further reading

• Claude Code Complete Guide
• Claude Code Best Practices
• AI Agent Team Framework with Claude Sub-Agents

References

• Agent Teams - Claude Code Docs
• Claude Code Setup
• Claude Code Settings
• Permissions
• Claude Code Overview