How to Use Claude Code for Team Development: Parallel Sessions, Agent Teams, and Shared Configuration

The Team Development Problem Claude Code Was Built to Solve

Most AI coding guides are written for one developer, one terminal, one session. But most real software is built by teams. When four engineers all reach for the same codebase, the collision problem appears immediately: conflicting edits, different mental models, inconsistent style, no shared context.

Claude Code has always solved the single-developer problem. In 2026, it solves the team problem too. This guide covers the three layers of team-scale Claude Code usage: shared configuration that every developer and every agent inherits automatically, git worktrees for parallel isolation, and the new experimental Agent Teams feature that lets Claude coordinate multiple instances automatically.

The practical outcome: a team that uses all three can have Claude working on four things at once, with zero edit conflicts, consistent code standards, and coordination that doesn't require a human to manage.

Layer 1: Shared Configuration with CLAUDE.md

Every Claude Code session reads a CLAUDE.md file automatically when it starts. For individual developers, this is where you put personal preferences. For teams, it is the single most important infrastructure decision you can make: a version-controlled file that gives every developer - and every agent - the same context, standards, and constraints.

What to put in your team CLAUDE.md

Commit a CLAUDE.md to your repository root with everything Claude needs to work correctly on your codebase:

• Tech stack and dependencies - what framework, language version, key libraries. Claude won't ask what ORM you're using if it's in the file.
• Code style and conventions - naming patterns, file organization, what a "good PR" looks like in this codebase. Include things your linter can't enforce.
• Architecture decisions - the key design choices that explain why things are structured the way they are. Prevents Claude from "fixing" things that are intentional.
• Testing requirements - what coverage is expected, what test frameworks you use, how to run the test suite. Claude should run tests before marking work done.
• PR workflow - branch naming conventions, required checks, what you want Claude to include in commit messages and PR descriptions.
• Out-of-bounds areas - files or directories Claude should never modify without explicit instruction (config files, migration files, generated code).

When you use Agent Teams, every spawned teammate loads this same CLAUDE.md automatically. You write the standards once; every agent instance follows them without any additional prompting.

The hierarchy: project, directory, and personal configuration

Claude Code reads CLAUDE.md files in a hierarchy:

1. Project root - ./CLAUDE.md - team-wide standards, committed to git
2. Subdirectories - ./packages/api/CLAUDE.md - module-specific rules that override or extend the root
3. Personal - ~/.claude/CLAUDE.md - individual developer preferences that apply across all projects

This hierarchy means a backend-focused developer can set personal preferences (like preferred error handling style) in their ~/.claude/CLAUDE.md without imposing them on teammates, while the team's architecture decisions live in the project root file that everyone and every agent inherits.

For a deep dive on CLAUDE.md structure, see our CLAUDE.md configuration guide.

Layer 2: Git Worktrees for Parallel Isolation

The simplest way for multiple developers to use Claude Code on the same codebase is git worktrees. A worktree is a separate directory with its own files and branch, sharing the same repository history and remote as your main checkout. Each developer runs Claude in their own worktree - edits never touch the other developer's files.

Starting a worktree session

One command creates an isolated worktree and starts Claude in it:

claude --worktree feature-auth

This creates .claude/worktrees/feature-auth/ in your repository root, on a new branch named worktree-feature-auth. Run the same command with a different name in another terminal:

claude --worktree bugfix-payment-timeout

Now two isolated Claude sessions are running simultaneously on the same repository. Each has its own context, its own branch, and its own files. Neither can accidentally overwrite the other's work.

Practical worktree setup for teams

Add .claude/worktrees/ to your .gitignore to prevent worktree contents from appearing as untracked files in your main checkout:

# .gitignore
.claude/worktrees/

If your project uses .env files or other gitignored configuration, add a .worktreeinclude file at the repository root. This file uses .gitignore syntax, and any matching gitignored files get copied automatically into each new worktree:

# .worktreeinclude
.env
.env.local
config/secrets.json

This way, every Claude worktree starts with the correct local environment without any manual setup.

Worktrees without Agent Teams

You don't need Agent Teams to use worktrees. The most common team pattern is the simplest one: each human developer runs Claude in their own worktree. When they're done, they open a pull request from their branch, it goes through the normal review process, and the worktree gets cleaned up on exit: Claude checks it when the session ends, removes a clean unnamed worktree automatically, and prompts you to keep or remove it if it's named or still has work in it.

Worktrees also work for automated parallel work without agent coordination. You can run three background Claude sessions in three separate worktrees, each handling a different refactor task, with no inter-agent communication needed.

Layer 3: Agent Teams - Automated Parallel Coordination

Agent Teams is an experimental feature (as of v2.1.178) that takes parallelism further: instead of separate human-driven sessions, a single lead Claude instance spawns multiple teammates that coordinate automatically through a shared task list.

Enabling Agent Teams

Agent Teams are disabled by default. Enable them in your settings:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or as an environment variable in your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Your first agent team

Once enabled, describe the task and the teammates you want in natural language:

# In your Claude session after enabling agent teams:

"Spawn three teammates to review this PR:

- One focused on security implications

- One checking performance impact

- One validating test coverage

Have them each review and report findings."

Claude creates a shared task list, spawns the three reviewers, has each run its specialized review, and synthesizes the findings. The security reviewer, performance reviewer, and test reviewer work simultaneously - a code review that would normally take three sequential passes happens in parallel.

When to use Agent Teams

Agent Teams add coordination overhead and consume significantly more tokens than a single session. They're worth the cost when parallel exploration genuinely speeds things up:

• Parallel code reviews - security, performance, and test coverage all analyzed simultaneously by reviewers with different lenses
• Debugging competing hypotheses - when the root cause is unclear, spawn teammates to investigate different theories in parallel and challenge each other's conclusions
• Building independent modules - frontend, backend, and tests for a new feature built simultaneously when the interfaces are agreed upfront
• Multi-perspective research - investigating a library, evaluating an architectural decision, or exploring a problem from different angles

For sequential tasks, same-file edits, or work with many inter-dependencies, a single session or subagents are more cost-effective.

How Agent Teams work under the hood

An agent team has four components:

• Team lead - your main Claude session, which spawns teammates and coordinates work
• Teammates - separate, fully independent Claude Code instances, each with their own context window
• Shared task list - the coordination mechanism; teammates claim tasks, mark them complete, and the lead tracks progress
• Mailbox - a JSON-based messaging system at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json that lets teammates message each other directly

Unlike subagents (which only report back to the main agent), teammates can communicate directly with each other. This matters for tasks like the debugging example above: each hypothesis investigator shares findings with the group, and the consensus emerges from debate rather than from sequential analysis.

Display modes: in-process vs split panes

Agent Teams support two display modes:

• In-process (default) - all teammates appear in an agent panel below your main prompt. Use arrow keys to select a teammate, Enter to view their session and interact directly.
• Split panes - each teammate gets their own terminal pane. Requires tmux or iTerm2 with the it2 CLI. You see everyone's output simultaneously and can click into any pane to interact.

Configure the mode in settings:

// ~/.claude/settings.json
{
  "teammateMode": "auto"
}

Or per session:

claude --teammate-mode auto

The "auto" mode uses split panes when you're already inside tmux or iTerm2 with it2 installed, falling back to in-process otherwise.

Subagents vs Agent Teams: Choosing the Right Tool

Claude Code offers three ways to parallelize work, with different tradeoffs. Here's when to use each:

The decision tree:

1. Multiple human developers working in parallel? Each gets their own worktree session
2. Automated parallel work where tasks are fully independent and only results matter? Subagents (cheaper)
3. Automated parallel work where agents need to share findings and challenge each other? Agent Teams

Managing Token Costs at Team Scale

Token costs are the friction point most teams don't plan for until their first surprise bill. At team scale, the math compounds quickly.

The baseline: single developer, single session

A typical engineering session - a few hundred turns, moderate tool usage - might use 500K-2M tokens. At Claude's API pricing, that's manageable for an individual. Multiply by 10 developers, or 5 parallel agent teammates, and the numbers change.

Agent Teams token scaling

Each teammate has its own full context window. Token usage scales linearly with the number of active teammates. A 3-teammate team roughly triples the token cost of the same work done sequentially by one agent. The Anthropic documentation is explicit: "Agent teams add coordination overhead and use significantly more tokens than a single session."

The practical guidance:

• Start with 3 teammates for most workflows, not 10. Three focused teammates usually outperform five scattered ones.
• Assign 5-6 tasks per teammate to keep everyone productive without too much context switching.
• Use Agent Teams only when parallel exploration genuinely reduces the total time or improves quality - not as a default for every task.
• For routine sequential development, a single session is almost always more cost-effective.

The Claude Max plan for heavy team usage

The Claude Max plan (up to $200/month per seat at the top tier) gives individual heavy users substantially higher usage limits than Pro - higher, not unlimited, so plan for limits rather than around them. For teams that hit limits regularly - especially teams doing Agent Teams experiments - Max is worth evaluating before the token cost compounds. See our guide on reducing Claude Code API costs for the full cost management playbook.

Hooks: Enforcing Quality Gates Across the Team

One of the underused team features is hooks - automated scripts that run at specific Claude Code lifecycle points. For teams, hooks are how you enforce standards automatically rather than relying on everyone to follow documentation.

For Agent Teams specifically, three hooks are particularly useful:

• TeammateIdle - runs when a teammate finishes and goes idle. Exit with code 2 to send feedback and keep the teammate working (for example: "You haven't run the test suite yet. Run npm test and address any failures before marking this complete.")
• TaskCreated - runs when a task is being created. Exit with code 2 to block task creation that doesn't meet your standards (for example: blocking tasks that don't include acceptance criteria).
• TaskCompleted - runs when a teammate tries to mark a task done. Exit with code 2 to require proof of completion.

// ~/.claude/settings.json
{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"Verify tests pass and types compile before finishing\" >&2; exit 2'"
          }
        ]
      }
    ]
  }
}

Combined with the team CLAUDE.md, hooks turn your development standards into automated enforcement rather than documentation nobody reads.

A Practical Team Setup Checklist

Here's the minimum viable team Claude Code setup:

1. Commit a team CLAUDE.md to the repository root with: tech stack, code conventions, testing requirements, PR workflow, and any out-of-bounds files. Every developer and every agent inherits this automatically.
2. Add .claude/worktrees/ to .gitignore to prevent worktree noise in your main checkout.
3. Create a .worktreeinclude file listing gitignored files (like .env) that should copy automatically to each worktree.
4. Run each developer in their own worktree when working in parallel. claude --worktree feature-name is all it takes.
5. Enable Agent Teams for exploration tasks where parallel analysis improves quality. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings file and start with 3 teammates for code reviews and debugging sessions.
6. Add TeammateIdle hooks to enforce test-before-done requirements automatically.

The compounding effect is real. A team where Claude runs with full project context, no edit conflicts, and automated quality enforcement ships faster than a team where each developer configures Claude individually and files merge conflicts daily.

What Agent Teams Can't Do Yet

Agent Teams is experimental and has real limitations worth knowing before you depend on it:

• No session resumption with in-process teammates - /resume and /rewind don't restore in-process teammates. If you resume, you'll need to respawn.
• Task status can lag - teammates sometimes fail to mark tasks complete, which blocks dependent work. Check whether work is actually done if a task looks stuck.
• One team per session - you can't have multiple named teams or share a team across sessions.
• No nested teams - teammates can't spawn their own teammates. Only the lead manages the team.
• Lead is fixed - the main session is the lead for its lifetime. You can't promote a teammate.
• Split panes require tmux or iTerm2 - not available in VS Code's integrated terminal or Windows Terminal.

For most team use cases today, worktrees plus subagents is the more stable path. Agent Teams are worth experimenting with for exploration tasks, but don't build critical workflows on them until the experimental flag comes off.

If you want to go deeper on AI-assisted team development and production agent workflows, join AI Builder Club. We run weekly deep-dives on what's actually working in real engineering teams.