Claude Code Subagents: How to Give Them Shared Context (2026)

TL;DR

Subagents in Claude Code are separate agent instances with their own context windows, spawned to handle a piece of work in parallel or in isolation. That isolation is the point: it keeps a long search from flooding the main conversation. It is also the problem, because each subagent starts blank, cannot see what its siblings learned, and returns only its final text. Sharing context between subagents means putting the shared knowledge somewhere both can reach, which is either a file on disk or an external memory layer. This guide covers how subagent context actually works and the four patterns teams use to coordinate them.

What is a Claude Code subagent?

A subagent is a separate Claude instance launched by the main agent with its own prompt, its own tools and its own context window. Anthropic's documentation describes them as a way to delegate work that would otherwise consume the primary context: a broad codebase search, a focused review, an independent verification pass.

Three properties define their behaviour:

1. They start with no history. A subagent receives the prompt it is given and nothing else from the parent conversation. What the parent has figured out over twenty turns is invisible unless it is restated.

2. They do not see each other. Two subagents running in parallel have no channel between them. Each can duplicate the other's work without either knowing.

3. They return text, not state. Whatever a subagent learned collapses into its final message. The reasoning, the files it read and the dead ends it ruled out are discarded.

Custom subagent types are defined in .claude/agents/*.md files with frontmatter controlling model, tools and description, so a team can standardise the roles it uses.

Why does subagent isolation cause problems?

Isolation is genuinely valuable. A search that reads two hundred files should not put two hundred files into your main context. The trouble is that isolation and coordination are opposites, and most real work needs both.

The failure modes that show up in practice:

1. Duplicated work. Three subagents asked to review three modules each independently read the same shared utility file and each spend context understanding it.

2. Contradictory conclusions. Two subagents reach different answers about the same behaviour because each saw a different subset of the code, and the parent has no basis for choosing between them.

3. Lost rationale. A subagent correctly rules out an approach, explains why in its working, and returns only the recommendation. The next subagent tries the ruled-out approach again.

4. Repeated onboarding cost. Every subagent that needs project conventions has to be given them, so the same instructions are paid for once per subagent rather than once per session.

None of these are bugs. They follow directly from the design, which is why the fix has to live outside the subagent mechanism.

What are the options for sharing context between subagents?

Four patterns, from simplest to most capable.

1. Restate context in every prompt. Include the conventions and findings in each subagent's prompt. Works, costs tokens linearly with subagent count, and goes stale the moment the parent learns something new.

2. Write to a shared file. Have each subagent append findings to a scratch file and have later subagents read it. This is the cheapest real coordination mechanism and it works well within a single session. It does not survive the session, and concurrent writes need care.

3. Use `CLAUDE.md` for the stable parts. Anything true of the repository regardless of task belongs here, and it loads automatically for every agent in the tree. This removes the repeated-onboarding cost for conventions specifically, and nothing else.

4. Query a shared memory layer over MCP. Both parent and subagents read from and write to a persistent store that resolves facts rather than storing raw text. This is the only pattern on the list where a finding from one subagent is available to a subagent spawned tomorrow, in a different repository, by a different person.

How do the coordination patterns compare?

The honest reading of this table: for a one-off parallel task inside one session, a shared file is the right answer and anything heavier is overkill. The case for a memory layer starts when findings need to outlive the session or cross a repository boundary.

What should go in a subagent prompt?

Independent of which pattern you choose, subagent prompts fail for predictable reasons, and a few rules fix most of them.

1. State the return contract explicitly. The subagent's final text is the return value, so say what shape it should take. Unstructured prose forces the parent to re-parse.

2. Give it the conclusion it needs to reach, not the process. Subagents are poor at inferring scope and good at executing a defined one.

3. Include what has already been ruled out. This is the single highest-value line in most subagent prompts and the one most often omitted.

4. Scope the tools. A subagent with write access to the repository when it only needs to read is an unnecessary risk, and tool lists are configurable per agent type.

5. Name what a negative result looks like. Without it, a subagent that finds nothing will often invent something rather than report an empty set.

FAQ

The decision rule

Use subagents when the work is genuinely independent and the context cost of doing it inline is high. Coordinate them with a shared file when the work is confined to one session. Move to a shared memory layer only when findings need to persist beyond the session or reach agents in other repositories, because that is the boundary a file cannot cross.