Claude Code subagents vs agent teams: how they work
Claude Code subagents are helpers inside one session. Each has its own context window and returns a result to the caller. Agent teams are separate sessions that message each other and share a task list; they are experimental and off by default. Neither shares memory with sessions outside the team.
Subagents: helpers that report back
A subagent is a specialist that Claude Code starts for one job. It gets its own context window, its own system prompt and its own tool permissions. When it finishes, it hands a result back to the agent that called it, so long searches and logs never fill your main conversation.
You define one as a Markdown file with a short header. Put it in .claude/agents/ for one project, or ~/.claude/agents/ for every project. The header needs a name and a description. Tools, model and permission mode are optional.
A subagent starts with its system prompt, the task message, your CLAUDE.md files and a git status snapshot. It does not see the main conversation unless it is a fork. So the task message has to carry everything it needs.
---
name: code-reviewer
description: Reviews code for quality and security. Use after edits.
tools: Read, Grep, Glob
model: sonnet
---
You are a code reviewer. Report specific, actionable problems.Agent teams: separate sessions that talk
An agent team is one lead session plus teammates. Each teammate is a full Claude Code session with its own context window. Teammates message each other by name, and the team shares a task list they can claim work from. You can also open any teammate and talk to it directly.
Teams are experimental and disabled by default. Turn them on with an environment variable, either in your shell or in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Which one to use
Use a subagent when only the result matters: run the tests, search the code, review one file. Use a team when the workers need to share findings and argue, such as reviewing a pull request from three angles or testing competing theories about a bug.
- Subagents cost fewer tokens because results come back summarized.
- Teams cost more, because every teammate is a separate session and usage grows with each one.
- Two workers editing the same file will overwrite each other, so give each teammate its own files.
- The Claude Code documentation suggests starting with three to five teammates.
- Teammates cannot start teams of their own, and one session can lead only one team.
Do they share memory or context?
Within a session, no. Each subagent and teammate has its own window, and the lead's conversation history does not carry over. What they share is what you pass in the task message, the project files and CLAUDE.md, and, in a team, the messages and the task list.
The limit is the boundary. A team lives inside one session on one machine, and Claude Code says resuming a session does not bring in-process teammates back. A second terminal running Codex, a Cursor window or a chat tab is outside the team entirely.
Where a shared node fits
If you want sessions from different tools to share one memory and one thread, you need something outside any single tool. A common way is a shared MCP server that every agent connects to. A NodePress node is one: it runs on your computer, and each agent joins with one pasted line. Agents then share a thread, a memory graph and the files you choose, and every step is written to one readable thread.
This does not replace subagents or teams. Keep using them inside a session. Use the node to connect that session to the others.
Do it with a NodePress node
- Name a node on nodepress.ai. It is free and needs no sign-up for the first one.
- Copy the one line it gives you and paste it into Claude Code. By hand, it is: claude mcp add --transport http nodepress https://nodepress.ai/mcp
- Paste the same line into your other agents, such as Codex or Cursor.
- Give the task to any of them. They read and write the same thread and memory.
- Watch the thread to see which agent did what and where one stopped.
If everything runs in one Claude Code session on one machine, subagents or a team are enough and a node adds nothing. For a short, sequential task, a single session is cheaper than either.
Questions people ask
Do Claude Code subagents share memory?
No. Each subagent has its own context window and returns a result to the caller. They share only what you pass in the task message and the files and CLAUDE.md they load.
Can Claude Code subagents talk to each other?
The Claude Code documentation says subagents that Claude named when it spawned them can message each other. By default they report to the caller. Agent teams are the feature built for direct messaging between workers.
How do I enable Claude Code agent teams?
Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your environment or in the env block of settings.json. Then ask Claude for teammates in plain language.
Do Claude Code agent teams cost more tokens?
Yes. Each teammate is a separate session, so usage grows with the number of active teammates. Anthropic's documentation recommends a single session for routine tasks.
Can Claude Code agents work with Codex?
Not inside a built-in team, which holds Claude Code sessions only. You can connect both tools to one shared MCP server so they use the same memory and thread.
Related
- How to build an AI agent swarm
- Multi-agent orchestration: patterns and when to use them
- How to stop AI agents overwriting each other's code
- How to use Claude Code, Codex and Cursor together
- How to get AI agents talking to each other
- How to get AI agents talking to each other