Claude Code subagents and agent teams: how they work and when to use them

Built-in subagents, how to create a custom one in .claude/agents, how to invoke it, and how experimental agent teams differ — with a ready-to-use code reviewer.

8 minutes Matěj Žalmánek 2026-10-26

A single Claude Code session has one context window, and everything ends up in it: every file it read, every test log, every dead end. On a big task it fills up and the agent starts forgetting what mattered. Subagents fix this by handing work to helpers with their own context, and agent teams go further with several full sessions that talk to each other. Here is how Claude Code agents work, how to create your own subagent, and when a team is worth it.

1. What are Claude Code subagents

A subagent is a specialized assistant that runs in its own context window, with its own instructions, its own set of tools and its own permissions. Claude hands it a task, the subagent works through it, and only a summary comes back to the main conversation.

That gives you three things:

• A clean main context. The 5,000 lines of search results stay in the subagent; you get the three files that matter.
• Restricted tools. A reviewer that can only read cannot accidentally “fix” anything.
• Cheaper models where they suffice. Searching and summarizing can run on a smaller model.

Subagent work counts toward the same usage limits as your main conversation.

2. Built-in subagents: Explore, Plan, general-purpose

• Explore — fast, read-only search and analysis of the codebase. Claude uses it on its own when it needs to find something.
• Plan — read-only research while you are in plan mode.
• general-purpose — multi-step tasks that need both exploring and changing things.

You do not have to do anything to use these; Claude delegates to them when it makes sense.

3. How to create a custom subagent

The quickest way: describe the subagent to Claude and tell it where to save it. Or write the file yourself — a Markdown file with a short header in .claude/agents/ (shared with the project) or ~/.claude/agents/ (yours, in all projects):

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use proactively after any significant change.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. Review the changes you are given.
For each problem, name the file and line, explain the risk, and
suggest a fix. Order findings by severity. Do not edit any files.

The fields that matter most:

• name and description are required. The description decides when Claude delegates; “use proactively” encourages it to do so on its own.
• tools is an allow list; leave it out and the subagent gets the usual tools. disallowedTools removes specific ones.
• model — sonnet, opus, haiku, a full model ID, or inherit.
• isolation: worktree runs the subagent in its own git worktree — see Git worktree with Claude Code.
• skills preloads skills, mcpServers gives it its own MCP servers, maxTurns caps how long it runs.

4. How to use subagents

• Automatically — Claude picks a subagent whose description fits the task.
• By asking — “use the code-reviewer subagent on my last commit”.
• By @-mention — type @ and pick the agent; it decides which subagent runs.
• As the whole session — claude --agent code-reviewer runs the session as that agent, with its tools and model.

Subagents can run in the foreground (you wait for the result) or in the background (you keep working; press Ctrl+B to send a running one there). Their permission prompts still come to you, labeled with the subagent's name.

One thing to remember: a subagent does not see your conversation. It gets its own instructions, the task Claude wrote for it and your CLAUDE.md. If a rule from the conversation matters, it has to be in the task or in the subagent's file.

5. Claude Code agent teams

Agent teams are experimental and off by default. Turn them on in settings:

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

Then describe the team in plain words:

Spawn three teammates to review PR #142: one focused on security,
one on performance, one on test coverage. Have them report findings.

Your session becomes the team lead. It spawns teammates — each a full, separate Claude Code session — keeps a shared task list they claim work from, and collects the results. Teammates can message each other directly, and you can talk to any of them yourself: select one in the agent panel with the arrow keys and press Enter. With tmux or iTerm2, each teammate can get its own split pane.

6. Subagents vs agent teams

7. When to use which — and when neither

• Subagents for searching, reviewing, running tests and anything that produces a lot of output you do not want in the main context.
• Agent teams for parallel review from different angles, debugging with several competing theories, or features split cleanly across layers. Start with three to five teammates; more adds coordination, not speed.
• Neither for sequential work or several agents editing the same files — one session is faster and cheaper there. And for parallel work you want to drive yourself, plain worktrees with separate sessions are often simpler.

Parallel agents also mean parallel questions. With coden the agent runs Claude Code on your computer — your subagent definitions in .claude/agents/ included — and the permission requests of the agent and its subagents come to your phone, so a long run does not have to keep you at the keyboard. Agent teams are a different story: they need an interactive terminal session, so they do not run inside coden.

Do you see it differently? Write to support@coden-app.com.