Jonathon's AI Wiki

Claude Code Subagents

3 min read

Source: ai-research (web research, 2026-04-11) Type: Product Feature Product: Claude Code

Subagents are isolated Claude instances spawned by a main session to handle specific tasks independently. Each subagent gets its own context window, custom system prompt, and scoped tool access. They run in parallel, return only their summary/results, and keep the main context window clean. This is the workhorse pattern for scaling Claude Code work.

How subagents work

  • The main session spawns one or more subagents, each with a defined task
  • Each subagent gets its own context window — isolated from the parent and from each other
  • Subagents can have different permissions: read-only, research-only, or full editing access
  • Custom system prompts scope each subagent to its specific task
  • Results flow back to the parent session as summaries — raw context is discarded
  • Multiple subagents run in parallel for throughput

Subagent types

  • Read-only — reviewers, auditors, code analysis. Cannot modify files.
  • Research — gather information, search codebases, read documentation. Read access only.
  • Code writers — create files, execute code, make changes. Full editing permissions.

Defining reusable agents

  • Store agent definitions in .claude/agents/ for project-level shared specialists
  • These become reusable across sessions and team members
  • Each definition specifies the system prompt, tool access, and permissions

Key Takeaways

  • Subagents keep the main context window clean by offloading work to isolated instances
  • Different permission levels (read-only, research, code writer) control what each subagent can do
  • Parallel execution means 3 subagents finish roughly 3x faster than sequential work
  • Reusable agent definitions in .claude/agents/ create project-level specialists
  • Subagents do NOT communicate with each other — use Agent Teams when peer coordination is needed
  • Custom system prompts + scoped tool access = precise control over each subagent’s behavior

Try It

  1. In Claude Code, ask for a task that benefits from parallelism (e.g., “Audit the security of the auth module while simultaneously writing tests for the payments module”)
  2. Observe how Claude Code spawns subagents with appropriate permissions
  3. Create a reusable agent: add a YAML file to .claude/agents/ with a specialist definition (e.g., security-reviewer.yml with read-only permissions and a security-focused system prompt)
  4. Use subagents liberally for research tasks — “have a subagent investigate how the caching layer works while I continue implementing the feature”

Open Questions

  • What is the maximum number of concurrent subagents before performance degrades?
  • How much context can a subagent return before the parent session’s context window is impacted?
  • Can subagent definitions in .claude/agents/ reference MCP servers or skills?

Graph View

Backlinks