Claude Code agent teams and subagents: how to set them up and keep track of every agent

Claude Code agent teams let one session act as a lead that spawns teammates: separate Claude Code sessions, each with its own context window, a shared task list, and the ability to message each other directly. As of October 2026 teams are experimental and off until you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Subagents are the lighter option: workers inside one session that take a side task and hand back a summary. Start with subagents, and reach for a team when the workers need to talk to each other.

Agent teams vs subagents

Both split work across fresh context windows. The difference is who coordinates and how much it costs:

Claude Code has a few other ways to run work in parallel, and they are easy to confuse with teams. Agent view (claude agents) dispatches independent background sessions that you check on yourself. Dynamic workflows run many subagents from a script. /batch splits one large change across 5 to 30 subagents, each in its own worktree. Cross-session messaging lets separate sessions you started pass findings between them.

Set up subagents

Claude Code already ships built-in subagents such as Explore and Plan, and delegates to them on its own. A custom subagent is a Markdown file with YAML frontmatter. Save it in .claude/agents/ for one project or ~/.claude/agents/ for all of them:

---
name: test-runner
description: Runs the test suite, reads failures and fixes them. Use after code changes.
tools: Read, Edit, Grep, Glob, Bash
model: sonnet
---

You run the project's tests with `npm test`. For each failure, find the cause,
make the smallest fix, and rerun until the suite passes. Report what you changed.

Only name and description are required, and the description is what Claude reads when it decides whether to delegate, so keep it short and specific. Other fields worth knowing: permissionMode, maxTurns, isolation: worktree (the subagent works in its own git worktree), background: true, memory for notes that persist across sessions, and skills to preload. You can also just ask Claude to write the file for you.

Three ways to use it, from a hint to a guarantee:

• Name it in your prompt: "Use the test-runner subagent to fix the failing tests."
• @-mention it: type @ and pick it, which writes @"test-runner (agent)" and guarantees that subagent runs.
• Run the whole session as it: claude --agent test-runner, or set "agent": "test-runner" in .claude/settings.json.

In an interactive session subagents usually run in the background while you keep working. Press Ctrl+B to background a running task, and use /tasks to check on, attach to or stop anything running. Permission prompts from a background subagent appear in your main session with the subagent's name on them.

Set up an agent team

Turn teams on in ~/.claude/settings.json (or export the variable in your shell):

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

Then describe the team in plain language. Independent roles work best:

Review PR 412 with three teammates: one on security, one on performance,
one checking test coverage. Have them share findings and challenge each other,
then give me one summary.

The lead creates tasks, spawns the teammates and collects their findings. Teammates load your project context (CLAUDE.md, MCP servers, skills) but not the lead's conversation, so put everything they need in the request. If Claude spawns ordinary subagents instead, ask again and say "agent team" explicitly.

Steer the team

• In-process mode (the default) works in any terminal. The agent panel under the prompt lists teammates: arrow keys to select, Enter to open a teammate's transcript and message it, x to stop one, Ctrl+T to toggle the task list.
• Split panes give each teammate its own pane. Set "teammateMode": "tmux" (or "auto") in settings; it needs tmux or iTerm2 with the it2 CLI, and doesn't work in VS Code's terminal, Windows Terminal or Ghostty.
• Plan first: put the lead in plan mode before asking for teammates, and each one plans read-only until its plan is approved. Note that the lead approves those plans by itself, without asking you.
• Shut down by name: "Ask the researcher teammate to shut down."
• Quality gates: TeammateIdle, TaskCreated and TaskCompleted hooks can exit with code 2 to keep a teammate working or reject a task. See the hooks guide.

Permissions and cost

Teammates start in the lead's permission mode. If the lead runs with --dangerously-skip-permissions, every teammate does too, so read the skip-permissions guide before combining them. Otherwise, teammate permission prompts show up in the lead's session for you to approve.

Each teammate is a full Claude session against your usage limits. Anthropic's guidance is 3 to 5 teammates for most work and about 5 to 6 tasks per teammate. Two teammates editing the same file will overwrite each other, and teams don't isolate teammates in worktrees, so split the work by file ownership.

Known limits (October 2026)

• /resume and /rewind don't restore in-process teammates. After resuming, tell the lead to spawn new ones.
• One team per session, no nested teams, and the lead can't be handed to a teammate.
• Task status can lag. If a task looks stuck, check whether the work is done and nudge the lead.
• Teams need an interactive session. With claude -p there are no teammates.

When to use which

• One task, lots of reading: a subagent. Searching a large codebase or reading logs in its own context keeps your main conversation clean.
• Several independent tasks you want back later: background sessions in agent view, each in its own worktree.
• One problem that benefits from debate: an agent team. Parallel code review and competing debugging hypotheses are the documented sweet spots.
• A sequential task or edits to the same few files: a single session. Coordination overhead outweighs the gain.

Keep track of several agents at once

More agents means more places something can be waiting on you. Inside one session, the agent panel and /tasks show what is running. Across sessions on one machine, claude agents groups background sessions into Needs input, Working and Completed, and claude agents --json gives scripts the same state.

Those views stop at one machine and one tool. When sessions run on a laptop and a server, or Codex and Cursor sit next to Claude Code, a shared board helps. Briefkin's hook keeps one card per session from every agent it supports, shows the agent's own todo list as a checklist, keeps a card in progress while background agents it started are still working, and pings Telegram only when a session is waiting on you. The dashboard guide compares it with the other options, and the docs cover setup.