Why Claude Code Agent Teams Don't Share Context — and How to Fix It (2026)

First, the honest framing: this is experimental and off by default

Before anything else — agent teams are disabled unless you turn them on. The documentation carries a warning: they're "experimental and disabled by default," enabled by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings or environment, and "without that variable, no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates."

So nothing here is a broken promise. It's a young feature with documented limitations, and the context boundary is a design decision rather than an oversight.

Coordination is shared; conversation is not

Look at what a team is made of, per the architecture section: a team lead, teammates, a shared task list, and a mailbox. The mailbox is a JSON file at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. The task list lives under ~/.claude/tasks/{team-name}/.

Those two things — tasks and messages — are the entire shared substrate. Teammates can see task status, claim available work, and message each other by name. What they can't see is each other's reasoning, or yours.

Compare it to subagents, which the docs do directly: subagents have their own context window and report results back to the caller; teammates have their own context window and are "fully independent," messaging each other rather than reporting up. Both models isolate context. Teams just add a channel.

The spawn prompt is the entire briefing

This is the practical consequence, and it's worth stating as a rule: whatever you want a teammate to know has to be in the spawn prompt, in a file it loads, or in a message someone sends it later.

The documentation's own best practice says as much — teammates load project context automatically "but they don't inherit the lead's conversation history," so you should "include task-specific details in the spawn prompt." Its example spawn prompt is several sentences long and specifies the module, the focus areas, the token-storage approach, and the output format.

Note who writes that briefing in practice: the lead, from its own compressed understanding of your conversation. Every teammate's starting knowledge is a summary written by another model, of a discussion you had, filtered through whatever the lead judged relevant.

Teammates get project context, not your context

The split matters. Teammates read CLAUDE.md from their working directory — the docs confirm "CLAUDE.md works normally" — plus MCP servers and skills from your project and user settings.

So committed, file-shaped knowledge propagates. Everything else doesn't. The constraint you mentioned in chat, the correction you gave the lead an hour ago, the decision you made in the meeting before you opened the terminal: none of that is in a file, so none of it reaches the team.

There's a related gotcha if you use subagent definitions as teammate types: the docs note that a definition's skills and mcpServers frontmatter fields "are not applied when that definition runs as a teammate," because teammates load skills and MCP servers from project and user settings like a regular session.

What a teammate learns dies with the team

Teams are session-scoped. The team name is derived from the session — session- plus the first eight characters of the session ID — and "the team config directory is removed when the session ends." The task list directory persists locally and is never uploaded, with retention governed by the same cleanupPeriodDays you use for transcripts.

So the tasks survive and the team doesn't. Nothing accumulates: the reviewer teammate that learned your error-handling convention this morning is gone this afternoon, and tomorrow's reviewer starts from the same spawn prompt. There's also no session resumption for in-process teammates — /resume and /rewind don't restore them, and the lead "may attempt to message teammates that no longer exist."

Messages are text, and deliberately low-trust

You might think the mailbox can carry the knowledge. It can carry sentences, and it's designed to be suspicious of them.

When one agent messages another, "Claude Code tells the receiving agent the message came from another Claude session, not from you." A teammate "can't approve a permission prompt or supply consent on your behalf," and a teammate denied an action "can't relay it to another teammate to bypass the check." In auto mode, a classifier treats a relayed approval claim as untrusted input and reviews each message before delivery, blocking some outright.

That's correct security design — and it means the mailbox is a coordination channel, not a knowledge bus. Also worth knowing the practical shape: to reach everyone you send one message per recipient.

And it costs real money to re-establish

The docs say plainly that agent teams "use significantly more tokens than a single session," scaling with the number of active teammates, and recommend 3–5 for most workflows. Part of what those tokens buy is each teammate independently reading the same files to reconstruct the same understanding — which is the expensive version of a problem a shared store solves once.

Writing enormous spawn prompts. The documented answer, and it works to a point. Then you're hand-authoring a briefing per teammate per session, and the briefing is a compression of your conversation — so the reason behind a constraint gets dropped exactly when a teammate would need it to make a judgment call.

Putting everything in `CLAUDE.md`. Correct instinct, since teammates do read it. The limit is size: the guidance is to keep instruction files short, because long ones consume context and get followed less consistently. A CLAUDE.md that holds everything four teammates need is one nobody follows.

Having the lead relay findings. Works, and it makes the lead a bottleneck that spends tokens rewriting what one teammate learned so another can read it. Also lossy in the same way as the spawn prompt.

Reading each teammate's transcript yourself. You can — select a teammate in the panel and press Enter to view and message it directly. Useful for steering, useless as a mechanism: you become the integration layer.

Using subagents instead. Sometimes right. Subagents cost less and report back, and the docs recommend them when workers don't need to talk to each other. It doesn't solve knowledge sharing either — subagents have the same isolation, minus the mailbox.

Keeping a scratch file in the repo. The most effective workaround, and it's a hand-rolled version of the right answer: a place outside any one agent's context that all of them read and write. Worth noting that this is what people converge on independently.

Keep the isolation. Independent context windows are why a five-agent team can work in parallel without drowning each other in output, and the low-trust messaging rules are protecting you.

What needs fixing is that "isolated context" currently means "isolated knowledge." Those are separable. Give the team a store outside every context window: the lead writes the constraints and decisions into it, teammates read it at the start of their work and write back what they discover, and the next team on the next day starts from what the last one learned instead of from a fresh spawn prompt.

MemoryLake is a memory layer for that — decisions, constraints, and source documents in one store, reachable over MCP from every teammate, from Codex, and from ChatGPT through the API. The task list coordinates the work; the store carries the knowledge.

Step 1: Create an API key

Generate a key and make your first request in about 30 seconds. Keep it in your environment or a secret manager rather than pasting it into a session.

Step 2: Upload your first memories

Drop in the documents, images, and files your teammates keep rediscovering: the architecture decisions with their reasons, the incident writeups, the API contracts, the conventions, the list of approaches you've already ruled out. Upload the sources rather than a summary — the spawn prompt is already a summary, and that's the layer that loses reasons.

Step 3: Connect your AI & agents

Give Claude, Codex, OpenClaw, and other AI agents access to memory via MCP or the API. Teammates load MCP servers from your project and user settings, the same as a regular session, so configuring the server once gives every teammate the same store — no per-teammate setup, and nothing that depends on the lead remembering to relay.

The first difference is that the spawn prompt gets shorter and better. Instead of compressing your whole conversation into a briefing, it says what this teammate owns and points at the store for the rest. Less lossy, less typing, and identical for every teammate.

The second is that a discovery survives the team. When the debugging teammate learns the retry endpoint is not idempotent, that goes in the store, and tomorrow's team inherits it. Right now that finding lives in a context window that gets torn down with the session.

The third is that parallel work stops re-deriving the same context five times. Each teammate reading a retrieved constraint is dramatically cheaper than each teammate reading the codebase to infer it — which matters given the docs' own warning that teams use significantly more tokens, and matters again for an agent that re-reads your codebase every session.

And it composes with what Claude Code already does. CLAUDE.md keeps carrying standing rules, auto memory keeps its local notes, and the task list keeps coordinating. None of them has to become the system of record — which they can't be anyway, since auto memory doesn't leave the machine that wrote it.

Write the constraints down before you spawn anyone

If you and the lead just spent forty minutes reaching a conclusion, that conclusion needs to exist somewhere a teammate reads. Ten minutes of writing before spawning saves you three teammates independently reinventing a rejected design.

Keep the spawn prompt about ownership, not education

Say what this teammate owns, what "done" looks like, and where to look for context. Trying to teach the whole project in a prompt is how briefings become 600 words that still miss the thing that mattered.

Give teammates predictable names

The lead names each teammate on spawn, and any teammate can message any other by that name. Tell the lead what to call them in your spawn instruction so you can reference them later — and remember that reaching everyone means one message per recipient.

Don't rely on messages to move knowledge

The mailbox is text, and incoming messages are treated as coming from another Claude session rather than from you, with permission claims explicitly untrusted. Use messages for coordination — "I'm done with the auth module" — and a store for facts.

Expect the team not to survive a resume

/resume and /rewind don't restore in-process teammates, and the lead may try to message teammates that no longer exist. If that happens, tell it to spawn new ones — and make sure the new ones can read what the old ones learned.

Start at 3–5 teammates and on read-only work

The documented recommendation, and it matches the failure mode: coordination overhead and token cost scale with team size, and parallel implementation invites file conflicts. Review, research, and competing-hypothesis debugging are where teams earn their cost.

Don't confuse any of this with enforcement

Instruction files and memory are context, not enforced configuration. If something must be true in every teammate's output — formatting, protected paths, no direct pushes to main — put it in a hook or CI, which applies to all of them without depending on what any one of them read.

Claude Code agent teams don't share context because teammates are independent by design: each has its own context window, each loads project context — CLAUDE.md, MCP servers, skills — and "the lead's conversation history does not carry over." What they share is a task list and a mailbox, and the mailbox deliberately treats agent-to-agent messages as untrusted for anything resembling consent. The team itself is session-scoped: the config directory is removed when the session ends, in-process teammates don't survive a resume, and nothing accumulates from one team to the next.

So keep the isolation and fix the sharing. Write the constraints and decisions into a store every teammate can read and write, keep the spawn prompt about ownership rather than education, and let the task list do coordination. Then five agents work from one understanding of your project instead of five compressions of your conversation.