Claude Code agent teams are an experimental feature that lets one Claude Code session act as a team lead. The lead spawns teammates, and each teammate is a full Claude Code session with its own context window. The teammates share a task list and message each other directly. You turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. A team lives inside a single session, so it is one of several ways to run more than one agent. The others are subagents, agent view, git worktrees and outside orchestration tools. This guide compares them and helps you pick one.
The five ways to run more than one Claude Code agent
Anthropic's own "Run agents in parallel" page lists five built-in options: subagents, agent view, agent teams, dynamic workflows and projects. It also covers worktrees and cross-session messaging as supporting tools. Add the third-party orchestrators and you get the landscape below.
1. Subagents: helpers inside one session
A subagent is a specialized assistant with its own context window, system prompt and tool permissions. It returns only a summary to the main conversation. Search results, logs and file dumps stay out of your main context. You define subagents as Markdown files in .claude/agents/ (one project) or ~/.claude/agents/ (all your projects). Only name and description are required. Optional fields include tools, model, isolation: worktree and memory, which gives the subagent a directory that persists across conversations. Claude Code also ships built-in subagents such as Explore, Plan and general-purpose.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Analyze the code and provide
specific, actionable feedback on quality, security, and best practices.Subagents are the cheapest option and suit focused jobs where only the answer matters.
2. Agent view: many background sessions, one screen
If you searched for "claude code agents view", this is the feature. Agent view is a research preview, and you open it with claude agents. It lists your background sessions grouped by state: needs input, working, completed. You can dispatch new sessions, peek at them, reply, and attach to the full conversation. claude --bg "<prompt>" starts a session straight in the background. Background sessions keep running after you close the terminal, and they survive machine sleep. A shutdown or restart stops them, but their saved conversations resume when you reply or attach. A session dispatched from agent view moves into its own git worktree before it edits files.
Note the naming trap: claude agents (agent view) and the in-session /agents command (subagent files) are different things.
3. Agent teams: a lead with teammates
The agent teams documentation says it plainly: the feature is "experimental and disabled by default." Enable it in your shell or in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Next, describe the team in plain language. For example: "Spawn three teammates to review PR #142: one on security, one on performance, one on test coverage." The lead fills a shared task list, spawns the teammates and puts the results together. In the default in-process mode, teammates show up in a panel below your prompt. Arrow keys select one, and Enter opens its transcript so you can message it. Setting teammateMode to "tmux" or "auto" gives each teammate its own split pane, which needs tmux or iTerm2 with the it2 CLI.
The documented limits matter more than the demo:
- One team per session, and the lead is fixed for the session's lifetime.
- No nested teams. Teammates cannot spawn their own teammates.
- No session resumption for in-process teammates.
/resumeand/rewinddo not restore them. - Interactive only. In
-pmode and Agent SDK sessions, Claude does not spawn teammates. - No worktree isolation. Teammates share your checkout, so split the work by file. Two teammates editing the same file overwrite each other.
- Cost. Each teammate is a separate Claude instance, so token use grows linearly with team size. Anthropic suggests starting with 3 to 5 teammates.
One side effect is easy to miss. While agent teams are enabled, any subagent that Claude names launches as a teammate. Teams can therefore form even when you didn't ask for one. Set the variable back to 0 if you only want subagents.
4. Parallel sessions with git worktrees
This is the manual way to run multiple Claude Code instances. A worktree is a separate checkout with its own branch that shares the repository history. claude --worktree feature-auth creates .claude/worktrees/feature-auth/ on a branch named worktree-feature-auth and starts Claude there. Run it again with a different name in another terminal and you have a second isolated agent. When you exit, Claude removes clean worktrees and asks before deleting one that has changes. You do the coordinating yourself, but nothing stops you from running Codex in a third worktree next to them. With cross-session messaging, sessions you run yourself can also pass findings to each other.
5. Orchestration tools outside Claude Code
Every built-in option above runs Claude sessions only. Anthropic's docs say "In every approach the workers are Claude sessions". To mix in other agent CLIs, or to keep agents running as long-lived workers, people use orchestration tools:
- Claude Squad is an open-source (AGPL-3.0) terminal UI. It manages Claude Code, Codex, OpenCode and Amp, giving each agent a tmux session and a git worktree.
- Conductor is a Mac app. It runs Claude Code, Codex, Cursor and OpenCode in parallel, and each task gets its own workspace, branch, diff and review path.
- Hivey is our own tool and an open-source terminal workspace. It runs Claude Code and Codex agents as swarms: each swarm has a coordinator (master) agent, a message bus, scheduled check-ins, an optional Slack channel and an optional Obsidian wiki.
Claude Squad and Conductor focus on parallel coding tasks with a clean branch-per-task review flow. Hivey focuses on persistent teams that keep a role, a brief and a memory across days.
Comparison table
We built this table from the official docs linked above. "Not documented" means we could not find the feature in the tool's own documentation. It does not mean the feature is impossible.
| Option | Scope | Persistence | Claude Code + Codex together | Scheduling | Remote / Slack | Memory |
|---|---|---|---|---|---|---|
| Subagents | Inside one session | Definitions are files; runs end with the task | No (Codex has its own subagents) | No | No | Optional memory directory per subagent |
| Agent view | Many background sessions on your machine | Survives closing the terminal and sleep; resumes after restart | No | No (cloud scheduled tasks are separate) | Not documented | CLAUDE.md and auto memory |
| Agent teams | One lead and its teammates in one session | Ends with the session; in-process teammates aren't resumed | No | No | No | Teammates load CLAUDE.md, MCP and skills; task list kept on disk |
| Worktrees + parallel sessions | Whatever you open | As long as you keep them | Yes, by hand | No | No | Each tool's own |
| Claude Squad | Many agents, one TUI | tmux sessions survive terminal disconnects | Yes | Not documented | Not documented | Not documented |
| Conductor | Many workspaces, Mac app | Workspaces until archived | Yes | Not documented | Not documented | Not documented |
| Hivey | Many swarms and solo agents | Keeps running after detach while the Mac is awake | Yes, in the same swarm | Yes (hivey swarm schedule) | Per-swarm Slack channel | Optional Obsidian wiki per swarm |
Two more Anthropic options are worth knowing. Dynamic workflows are scripts that run many subagents and cross-check their results, which suits audits and big migrations. Projects are a public beta on Pro, Max and Ultra plans. A project runs parallel cloud sessions from one ongoing conversation and keeps going while your machine is off.
When one agent is enough
Running agents in parallel multiplies token use, and Anthropic's docs repeat that warning on every page. Stay with one session, or one session plus a subagent, when:
- The task is sequential, so each step depends on the previous one.
- The changes touch the same few files. Parallel edits there cause conflicts, not speed.
- You would review every change anyway. Five agents waiting on one human is not faster than one.
- The job takes minutes, not hours. Setting up a team costs more than it saves.
Use agent teams when the work splits into independent parts that benefit from discussion. Examples are a review from several angles, debugging with competing hypotheses, or frontend, backend and tests owned separately. Use a swarm orchestrator when the agents need to outlive a session: a research agent that checks sources every morning, or a coordinator that keeps three workers busy on a product for a week.
A practical setup, from light to heavy
Step 1: give your main session good subagents
Put two or three subagent files in .claude/agents/, such as a read-only reviewer and a test runner, and commit them so the whole team gets them. If they share skills, the article on skills vs agents vs AGENTS.md explains where each piece of instruction should live.
Step 2: try an agent team on a review
Anthropic recommends starting with tasks that don't write code, like reviewing a PR or researching a library. Enable the variable, then ask:
Spawn three teammates to review the auth module:
- one focused on security
- one on performance
- one on test coverage
Name them sec, perf and tests. Wait for all three before summarizing.Pre-approve common commands in your permission settings first. Teammate permission prompts surface in the lead session and can pile up.
Step 3: isolate parallel coding with worktrees
claude --worktree feature-auth # terminal 1
claude --worktree fix-billing # terminal 2
git worktree list # see both checkoutsAdd .claude/worktrees/ to .gitignore. If each worktree needs local config files, list them in a .worktreeinclude file. A better move is to keep secrets out of files entirely with opaque references from EnvSave, so a copied file never holds a real key. Our guide to Claude Code API key setup covers this.
Step 4: run standing teams with a swarm orchestrator
When you want agents that keep their roles for days, mix Claude Code and Codex, or wake up on a timer, an orchestrator does the bookkeeping. Here is a Hivey setup:
npm install -g @hivey/cli
hivey setup
cd ~/projects/my-app
hivey swarm new "Research, build and test a pricing page"A creator agent designs the team with you and launches it in its own space. When you launch a swarm by hand, --kinds scout=codex runs one member on Codex while the rest stay on Claude Code. Here is real output from one of our machines (paths removed). It shows a six-agent swarm with a critic next to several long-running solo agents:
$ hivey swarm list
hivey
⬢ hivey master working opus
app-ideas
◆ coordinator master gone
● market-analyst worker gone sonnet
● marketer worker gone sonnet
● scout worker gone sonnet
● strategist worker gone opus
✎ critic critic gone opus
trading
★ trading master gone opus
▷ slack-relay script script
youtube-wiki
★ youtube-wiki master idle opus ✉ 1 queued
▷ slack-relay script script
ai-radar
★ ai-radar master idle opus
▷ slack-relay script script"gone" means the agent's process isn't running right now. hivey swarm relaunch <slug> restarts it and continues its conversation. Messages wait in a queue and arrive only when an agent is idle (✉ 1 queued above), so nobody is interrupted mid-task. Scheduled check-ins wake the coordinator on a timer:
hivey swarm schedule add my-app --at 09:00 "summarize yesterday's progress for the user"
hivey swarm schedule add my-app --every 30m --to critic "review anything marked DONE"Be honest about the trade-off. Hivey runs on your machine, ships prebuilt for Apple Silicon Macs, and stops when the Mac sleeps. It is not a hosted service. If you need agents that run while your laptop is closed, look at Anthropic's cloud Projects and scheduled tasks instead.
How to choose
- A noisy side task? Use a subagent.
- Several independent tasks you want to check on later? Use agent view (
claude agents). - One problem that benefits from several minds talking? Use agent teams. Stay within their limits and split files by owner.
- Parallel code changes you will merge yourself? Use worktrees, or Claude Squad or Conductor if you want a UI on top.
- Long-lived teams with roles, schedules, Slack and memory, across Claude Code and Codex? Use a swarm orchestrator like Hivey. Running it from your phone is covered in our Claude Code Slack integration guide.
Whatever you pick, the skills your agents load matter as much as how many agents you run. See Claude Code skills best practices. To share a proven team setup with someone else, Skylls publishes each skill, agent or swarm to its own private GitHub repo.
Try it
Start small: one subagent, then one agent team on a review. Reach for an orchestrator only when your agents need to keep working after you close the session. When that time comes, Hivey is free and open source: install it with npm install -g @hivey/cli and give it a goal. If you'd rather have someone design an agent team around your business, talk to AIagentsLab.