How to Set Up Claude Code Agent Teams: Build Apps with Multiple AI Agents

If you have been running a single Claude Code session and waiting for it to finish one task at a time, you are leaving serious speed on the table. Claude Code Agent Teams lets you spin up multiple AI agents that work on your codebase simultaneously — each with its own full context window, its own tasks, and the ability to message each other directly.

In this guide, I will show you exactly how to set up Claude Code Agent Teams from scratch, step by step. By the end, you will have multiple agents working in parallel on your project. No fluff, no theory dumps — just the hands-on setup.

What Are Claude Code Agent Teams?

Claude Code Agent Teams is an experimental feature that coordinates multiple independent Claude Code instances working together on the same codebase. Instead of one AI coding session doing everything sequentially, you get a team lead agent that creates tasks and spawns teammate agents — each running as its own full Claude Code session with a dedicated 200K token context window.

Here is the key part: teammates can communicate with each other directly using peer-to-peer messaging. The lead agent does not have to be the bottleneck. They share a task list with dependency tracking, so agents claim work, complete it, and move on to the next available task automatically.

Anthropic released Agent Teams on February 5, 2026, as a Research Preview running on Opus 4.6. It works on all Claude plans — Pro, Max, Teams, Enterprise, and API.

How the Architecture Works

Under the hood, agent teams use six core tools:

Tool	What It Does
TeamCreate	Creates a new team and spawns teammates
TaskCreate	Defines tasks with descriptions and dependencies
TaskUpdate	Claims tasks and updates their status
TaskList	Queries all tasks and their current state
SendMessage	Sends messages between teammates (peer-to-peer)
TeamDelete	Cleans up team resources when done

The file-based messaging system lives at ~/.claude/teams/{team-name}/inboxes/, and the shared task list tracks dependencies so agents do not start work before prerequisites are finished.

Agent Teams vs Subagents: What Is the Difference?

This is a common point of confusion. Claude Code has subagents (the Agent tool) and Agent Teams. They are different:

	Agent Teams	Subagents
Communication	Peer-to-peer between all teammates	Only report back to the parent
Context	Each agent gets its own full 200K window	Share the parent's context window
Coordination	Shared task list with dependency tracking	Parent manages everything manually
Best for	Parallel, independent workstreams	Quick, delegated subtasks

Rule of thumb: If you have 3+ independent modules that can be built in parallel (like a database layer, API layer, and frontend), use Agent Teams. If you need to quickly delegate a single research or coding task within your current session, use a subagent.

Prerequisites

Before starting, make sure you have:

• Claude Code CLI installed and working (run claude in your terminal to verify)
• A valid Claude plan (Pro, Max, Teams, Enterprise, or API)
• macOS or Linux (Agent Teams uses tmux or iTerm2 for split-pane display)
• Git initialized in your project folder

That is it. No extra plugins, no additional API keys. If you can run Claude Code, you can run Agent Teams.

Step 1: Install tmux (or iTerm2)

Agent Teams needs a terminal multiplexer to display each teammate in its own split pane. You have two options: tmux (works on macOS and Linux) or iTerm2 (macOS only, native panes).

Option A: tmux (Recommended for Linux and macOS)

tmux is a terminal multiplexer — it lets you run multiple terminal sessions inside a single window.

On macOS (using Homebrew):

brew install tmux

On Ubuntu/Debian:

sudo apt update && sudo apt install tmux

On Fedora/RHEL:

sudo dnf install tmux

Verify the installation:

tmux -V

You should see something like tmux 3.x. If you get "command not found," the install did not work — double-check your package manager.

Option B: iTerm2 (macOS Alternative)

If tmux gives you trouble — agents crashing silently, panes dropping back to the shell prompt — iTerm2 is a solid alternative. Claude Code can create native iTerm2 split panes without tmux.

Step 1: Download and install iTerm2.

Step 2: Install the it2 CLI (this is what Claude Code uses to create panes):

pip3 install it2

Verify it installed:

it2 --version

You should see something like it2, version 0.2.3.

Step 3: Enable the Python API in iTerm2:

• Open iTerm2 → Settings → General → Magic → check "Enable Python API"

Step 4: Restart iTerm2.

Important: When using iTerm2, you must run claude directly inside iTerm2 — not inside VS Code's terminal, not inside Terminal.app. Claude Code detects the TERM_PROGRAM environment variable to know it is running in iTerm2.

Step 2: Configure Claude Code Settings

Agent Teams is experimental and disabled by default. You need to opt in by updating your Claude Code settings file.

Run this command to create or update your settings:

cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "preferences": {
    "teammateMode": "tmux"
  }
}
EOF

Here is what each setting does:

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: Enables the Agent Teams feature. Set to "1" to turn it on.
• teammateMode: Controls how teammates are displayed. Set to "tmux" for split panes (works with both tmux and iTerm2 — Claude auto-detects your terminal). Set to "in-process" if you want all agents in a single terminal window, navigated with Shift+Down.

Important: If you already have a settings.json with other configuration, do not overwrite it. Instead, merge these two keys into your existing file.

Known Issue: Settings Not Being Picked Up

There is a known bug in some Claude Code versions where the teammateMode setting in settings.json is not properly parsed. If your agents run in-process instead of split panes despite the setting, use the CLI flag as a workaround:

claude --teammate-mode tmux

This flag overrides the settings file and reliably enables split-pane mode.

Step 3: Start a tmux Session

Before launching Claude Code, start a tmux session. This is required for the split-pane display to work.

tmux new-session -s claude-work

This creates a new tmux session named claude-work. You will see your terminal inside tmux now — the green bar at the bottom confirms it.

Tip: If you get disconnected or need to reattach later, run tmux attach -t claude-work.

If you are using iTerm2 instead of tmux: Skip this step entirely. Just open iTerm2 and go straight to Step 4. Claude Code will create native iTerm2 split panes automatically — no tmux session needed.

Step 4: Launch Claude Code

Inside your tmux session (or directly in iTerm2), navigate to your project folder and launch Claude Code:

cd your-project-folder
claude

If split panes are not appearing, use the CLI flag to force split-pane mode:

cd your-project-folder
claude --teammate-mode tmux

Claude Code will start with Agent Teams enabled. You will not see any visible difference yet — the team tools become available when you ask Claude to create a team.

Pro tip: Before creating a team, make sure your project has a CLAUDE.md file at the root. Every teammate loads this file as shared context, so put your project spec, stack decisions, folder structure, and coding conventions in there. This is how teammates know what they are building.

Step 5: Create Your Agent Team

Now tell Claude to create a team. Be specific about the roles and responsibilities. Here is an example prompt:

Create a team for building this project.

Teammate 1 "db-engineer": You are the database engineer. Design and implement
the database schema, migrations, and seed data.

Teammate 2 "backend-dev": You are the backend developer. Build the API routes,
middleware, authentication, and error handling.

Teammate 3 "frontend-dev": You are the frontend developer. Build the React
components, pages, routing, and styling.

Teammate 4 "integrator": You are the integration specialist. Connect the
frontend to the backend, configure CORS, set up environment variables,
and write tests.

Claude (as the team lead) will:

1. Call TeamCreate to spawn the teammates
2. Call TaskCreate to define work items with dependencies
3. Teammates appear as new panes in your tmux window
4. Each teammate immediately calls TaskList to find work and starts coding

You will see your tmux window split into multiple panes — one per teammate — each working independently.

How Many Agents Should You Use?

One agent per independent workstream. More agents does not mean faster. If two agents touch the same files, you get conflicts. For most projects:

• Small project (1-2 modules): Just use a single Claude Code session
• Medium project (3-4 modules): 3-4 teammates + 1 lead
• Large project (5+ modules): 4-5 teammates + 1 lead (diminishing returns beyond this)

Step 6: Monitor Your Agents

While agents are working, the lead agent monitors progress through the shared task list. You can also ask the lead at any time:

Show me the current task list and status of all agents.

The lead will call TaskList and give you a summary of what each teammate is doing, which tasks are completed, and what is blocked.

Peer-to-Peer Communication

One of the most powerful features: teammates can message each other directly. If the frontend developer needs to know the exact API response shape, it can send a message to the backend developer without going through the lead.

You will see these SendMessage calls in the tmux panes as they happen.

Switching Between Panes

Use these tmux shortcuts to navigate:

• Ctrl+B then arrow key — Move between panes
• Ctrl+B then z — Zoom into a single pane (press again to zoom out)
• Ctrl+B then q — Show pane numbers

Step 7: Exit When Done

When all tasks are complete and you are satisfied with the output, simply type:

/exit

This will shut down all teammates and clean up the team resources. The lead agent calls TeamDelete automatically.

Note: If you exit before all tasks are done, in-progress work is still saved in your project files — you just lose the team coordination state. You can always start a new team to continue.

Useful tmux Commands

If you are new to tmux, here are the commands you will actually use:

Command	What It Does
tmux new-session -s name	Create a new session
tmux attach -t name	Reattach to a session
tmux kill-session -t name	Kill a session
Ctrl+B then d	Detach from session (keeps it running)
Ctrl+B then arrow key	Switch between panes
Ctrl+B then z	Zoom/unzoom a pane
Ctrl+B then [	Scroll mode (use arrow keys, q to exit)
Ctrl+B then %	Split pane vertically
Ctrl+B then "	Split pane horizontally

The main thing to remember: Ctrl+B is the prefix key. Press it first, release, then press the second key.

Best Practices for Agent Teams

After testing Agent Teams on multiple projects, here is what I have learned:

1. Write a Solid CLAUDE.md

This is the most important step. Your CLAUDE.md is the shared brain for every agent. Include:

• Project name and description
• Tech stack with specific versions
• Folder structure conventions (e.g., src/api/ for backend, src/client/ for frontend)
• Coding standards (linting rules, naming conventions)
• Any context teammates need that you discussed with the lead

2. Design for Parallelism

Split your project into modules with clear file ownership. If Agent 1 owns src/db/ and Agent 2 owns src/api/, they will never conflict. If both agents need to edit src/index.ts, you will have problems.

3. Set Task Dependencies

Use the dependency system. If your API routes depend on the database schema being done first, encode that dependency. This prevents agents from starting work before prerequisites are ready.

4. Keep Teams Small

4-5 teammates is the practical maximum for most projects. Beyond that, coordination overhead eats into the speed gains. And remember — token cost scales linearly with the number of agents. Roughly 3-4x a single session for a 4-agent team.

5. Use Quality Gate Hooks

Set up TaskCompleted hooks to run linting or tests when an agent marks a task as done. This catches issues early before they cascade.

Common Issues and How to Fix Them

Same-File Conflicts

Problem: Two agents edit the same file simultaneously.

Fix: Plan your file ownership upfront. Each agent should work in its own directory. If shared files are unavoidable, assign one agent as the owner of that file.

Task Status Lag

Problem: An agent starts work on a task whose prerequisite is not actually done yet.

Fix: Always set explicit task dependencies with TaskCreate. Do not rely on agents checking informally.

Context Isolation

Problem: A teammate does not know about something you told the lead agent.

Fix: Put critical context in CLAUDE.md or in the task description itself. Teammates do not see the lead's conversation history.

Session Resumption

Problem: You cannot resume a team after disconnecting.

Fix: This is a known limitation of the Research Preview. If you lose the session, you will need to create a new team. Your files are preserved — only the coordination state is lost.

Agents Crash Silently in tmux Panes

Problem: Teammates spawn in tmux split panes but immediately exit back to the shell prompt with no error message.

Fix: This is a known issue with tmux-based split panes on some setups. Try these in order:

1. Use the CLI flag: Run claude --teammate-mode tmux instead of relying on settings.json
2. Switch to iTerm2: Install iTerm2 + the it2 CLI (pip3 install it2), enable the Python API, and run Claude directly in iTerm2
3. Use in-process mode: Run claude --teammate-mode in-process — agents work fine but all run in a single terminal (use Shift+Down to cycle between them)
4. Clean up stale team data: Run rm -rf ~/.claude/teams/* ~/.claude/tasks/* before retrying

Split Panes Not Appearing Despite Settings

Problem: You set teammateMode: "tmux" in settings.json but agents still run in-process.

Fix: This is a known parsing bug. The settings file value gets ignored in some versions. Use the CLI flag instead:

claude --teammate-mode tmux

When to Use Agent Teams (and When Not To)

Use Agent Teams When:

• Your project has 3+ independent modules (database, API, frontend, tests)
• You are building a full-stack app with clearly separable layers
• You are working on a monorepo with multiple packages
• You need to scaffold a project with many independent files
• You want to parallelize work that would take a single agent 60+ minutes

Do NOT Use Agent Teams When:

• Your task is sequential (step A must finish before step B, which must finish before step C)
• Your code is tightly coupled (most files depend on each other)
• You are making a small fix or working on a single file
• You are on a tight token budget (teams use 3-4x the tokens)

Conclusion

Claude Code Agent Teams turns one AI coding session into a coordinated team of parallel agents. The setup takes under 5 minutes: install tmux (or iTerm2 on macOS), add two lines to your settings, and tell Claude to create a team.

The real power is in how you structure your work. Design for parallelism, write a clear CLAUDE.md, set task dependencies, and keep agents in their own lanes. For the right kind of project — full-stack apps, monorepos, anything with 3+ independent modules — this is a serious productivity multiplier.

It is still a Research Preview, so expect rough edges. But even now, I am seeing 2-3x speedups on projects that fit the parallel pattern.

What to Do Next

• Watch the full build tutorial on my YouTube channel where I build a complete app with 5 agents from scratch
• Follow me on LinkedIn for daily AI coding tips
• Subscribe to my newsletter at codewithmuh.com for weekly tutorials

Found this helpful? Share it with a developer friend who uses Claude Code.

Written by Muhammad Rashid — I make hands-on tutorials about AI coding tools, AI agents, and automation at codewithmuh.com. Every week I build real projects with the latest AI tools so you can see what actually works.