Context Management & Worktrees

Knowledge

Every Subagent Has Its Own Context

The central principle of Subagents: Isolation. When the main agent starts a Subagent, it gets its own fresh context window. The Subagent doesn't see what the main agent previously read or wrote -- it starts with a clean workspace.

What the Subagent receives:

• The task description from the main agent
• Its system prompt (for Custom Agents, from the frontmatter)
• Access to the codebase through its allowed tools

What the Subagent does not see:

• The main agent's previous conversation history
• Files the main agent has read (unless explicitly mentioned)
• Results from other Subagents

At the end, the Subagent delivers a summary back. Only this summary enters the main agent's context -- not all the intermediate steps.

Git Worktrees: True Filesystem Isolation

By default, a Subagent works in the same directory as the main agent. If the Subagent changes files, the main agent sees these changes immediately. This can lead to conflicts.

The solution: Worktree isolation. With isolation: worktree in the frontmatter, the Subagent gets its own Git Worktree -- a separate working copy of the repository:

---
name: feature-builder
description: Implements features in isolated worktree
isolation: worktree
model: sonnet
tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Bash
---

Implement the feature in the isolated worktree.
When you're done, describe the changes.

What happens with isolation: worktree:

1. Claude Code automatically creates a new Git Worktree
2. The Subagent works in this separate directory
3. Changes in the worktree don't affect the main directory
4. After completion, the worktree is automatically cleaned up

Background Tasks with Ctrl+B

Subagents can be started as background tasks. Press Ctrl+B in Claude Code to move the current task to the background. You can then continue working while the Subagent completes its task.

Alternatively, you can set background: true in the Custom Agent:

---
name: long-analysis
description: Deep codebase analysis
background: true
model: haiku
tools:
  - Read
  - Grep
  - Glob
---

Background tasks are particularly useful for:

• Lengthy research (searching the entire codebase)
• Parallel work (you code, the agent analyzes)
• CI/CD-like checks (linting, test analysis in the background)

Persistent Memory for Subagents

Subagents can access Claude Code's memory system. Through the memory field in the frontmatter, you set the scope:

• user -- Access to ~/.claude/CLAUDE.md (global preferences)
• project -- Access to the project CLAUDE.md (coding standards, architecture)
• local -- Access to local memory files

This way, a code reviewer can automatically know the project's coding standards without you having to explain them every time.

Preloaded Skills

With the skills field in the frontmatter, Skills are fully injected into the Subagent context -- not just as a discovery reference, but as complete content:

---
name: test-writer
skills:
  - testing
  - typescript-patterns
---

The Subagent starts immediately with the knowledge from these Skills without having to search and load them first.

Subagent-Specific MCP Servers

Through mcpServers in the frontmatter, you can give a Subagent access to specific MCP servers:

---
name: issue-tracker
mcpServers:
  - linear
  - github
---

This gives the agent access to external systems relevant to its task -- without the main agent having to load these server connections.

Understand

The Interplay of Context and Worktree

Imagine two levels of isolation:

Context isolation (always active): The Subagent has its own context window. This is the "desk" -- what it reads and thinks stays with it. Only the result goes back.

Filesystem isolation (optional, via isolation: worktree): The Subagent works in a separate copy of the code. This is the "office room" -- its file changes don't affect the main directory.

For pure research, context isolation is sufficient. For Subagents that write code, worktree isolation is often the safer choice.

Apply

A typical workflow with worktree isolation:

1. You're working on Feature A in the main directory
2. You start a Subagent with isolation: worktree for Feature B
3. The Subagent implements Feature B in its own worktree
4. You review the changes and merge them if needed
5. The worktree is automatically cleaned up

This is especially powerful in combination with background tasks: You code on Feature A while the Subagent implements Feature B in an isolated worktree in the background.

Reflect

Context management is the foundation of efficient Subagent usage. Context isolation keeps your main agent lean, worktree isolation prevents file conflicts, and background tasks enable parallel work. In the next section, you'll learn when to choose which delegation strategy.