Claude Code Subagents: How to Orchestrate Multi-Agent Tasks

Claude Code subagents solve a specific problem: complex tasks are not one problem, they are five problems in parallel. Writing a new feature involves the API layer, schema changes, tests, documentation, and security review simultaneously.

Subagents handle this by splitting one complex task into coordinated subtasks. A primary orchestrator directs the work and synthesises the results. This is how you give Claude Code genuinely complex work without running one enormous, fragile prompt.

Key Takeaways

• Orchestrators spawn subagents mid-task: The primary agent plans the work and delegates to subagents using the Task tool. You write one orchestrator prompt, not multiple separate sessions.
• Subagents are full API sessions: Each subagent has its own context window, tool calls, and execution history. They are not lightweight threads.
• Permissions inherit from the orchestrator: Subagent permission boundaries come from the orchestrator's CLAUDE.md. There is no per-subagent configuration at runtime.
• Subagents do not talk to each other: All communication routes through the orchestrator. Subagents return results to the orchestrator, which synthesises them.
• Use subagents for internal parallelism: One complex task with multiple workstreams suits subagents. Multiple unrelated independent tasks suit parallel agents.
• Orchestrator prompt design determines output quality: How you specify decomposition and synthesis is as important as the subtask instructions themselves.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

What Are Claude Code Subagents and How Do They Work?

Claude Code subagents are full Claude API sessions spawned by a primary orchestrator instance during task execution. The orchestrator identifies subtasks, delegates them using the Task tool, receives the outputs, and synthesises the results. Subagents handle one bounded subtask each and return their output to the orchestrator.

The spawning mechanism is precise. The orchestrator passes each subagent a subtask description, relevant file context, and completion criteria.

• The orchestrator's full role: Plans the overall task, decomposes it into subtasks, delegates via Task tool calls, monitors completion, synthesises outputs, and handles failures.
• What a subagent does: Reads relevant files, executes one assigned subtask, and returns the output. It sees only its own task, not the full context.
• Full API sessions, not threads: Each subagent has its own context window and execution history. Token costs and API limits apply per subagent session.
• No peer-to-peer communication: Subagents are fully isolated. They are unaware of other subagents running in parallel. All coordination happens through the orchestrator.
• Synthesis is required: The orchestrator must combine subagent outputs into a coherent result. Merging code, assembling documentation, or compiling findings all happen at the orchestrator level.

Understanding how subagents fit within the broader agentic execution patterns available in Claude Code helps you choose the right execution model for each task type.

How Does the Orchestrator Coordinate Subagents?

The orchestrator prompt must specify four things: the overall task goal, how to decompose it into subtasks, what each subagent should produce, and how to synthesise the outputs. Poorly designed orchestrator prompts are where most subagent implementations fail.

Most guides cover subagent spawning and skip orchestrator design. This is the section where real implementations either work or do not.

• Task decomposition strategies: Decompose by concern (API layer, database layer, test layer), by module (payments, notifications, auth), or by stage (implementation, review, documentation).
• Define synthesis explicitly: Specify what "combined" means for your task. Merging code files, assembling documentation sections, and compiling review findings each require different synthesis instructions.
• Handle failures in the prompt: Specify whether the orchestrator should retry a failed subagent, adapt the plan without that output, or escalate to you. Default behaviour on failure is not reliable.
• Subtask boundary precision matters: Vague subtask descriptions produce overlapping outputs that are difficult to synthesise. Each subagent should have a single, non-overlapping scope.
• Completion criteria per subagent: Tell each subagent exactly what a complete output looks like. "Write the tests" is less reliable than "Write unit tests for all public methods in /src/api/users.js."

For teams managing larger multi-agent systems, the Claude Dispatch coordination layer provides infrastructure for orchestrating agent fleets beyond what a single orchestrator can manage.

How Do You Configure Subagent Permissions?

Subagents inherit their permission model from the orchestrator session's CLAUDE.md. There is no separate per-subagent permission configuration at runtime. You set the boundaries once, at the orchestrator level, and they apply to all subagents it spawns.

This is the most commonly misconfigured part of subagent setups. Permissions need to be defined before the orchestrator runs.

• What to define in CLAUDE.md: Pre-approved tool calls (which bash commands subagents can run), file scope boundaries (which directories each subagent can write to), and prohibited operations.
• Scope constraints by subagent type: A test-writing subagent should only write to /tests/. Enforce directory boundaries in the instruction file even though CLAUDE.md applies globally.
• MCP tools for subagents: External service connections configured in the orchestrator session are available to subagents. Configure MCP connections before launching the orchestrator, not after.
• The --allowedTools flag: When spawning subagents programmatically, restrict the tool set per subagent at the command level. A review subagent should not have write permissions. A documentation subagent should not run bash commands.
• Least-privilege principle: Give each subagent only the permissions its specific subtask requires. Broader permissions than necessary create unnecessary risk across the full run.

What Is the Difference Between Subagents and Parallel Agents?

Subagents are spawned automatically by an orchestrator mid-task. Parallel agents are launched manually by the user as separate claude commands. The key distinction is coordination: subagents are coordinated by the orchestrator; parallel agents are independent and unaware of each other.

The choice between them is not a preference. It follows directly from the task structure.

• Subagents are for one complex task: Use them when a single task has multiple natural workstreams that can run simultaneously and must be synthesised into one output.
• Parallel agents are for independent tasks: Use separate claude -p commands in separate worktrees for multiple unrelated tasks that happen to run at the same time. Full setup at parallel agent setup.
• Configuration differs: Subagents need a well-designed orchestrator prompt covering decomposition and synthesis. Parallel agents need well-scoped individual prompts and a manual merge strategy.
• Merge responsibility differs: With subagents, the orchestrator merges outputs automatically. With parallel agents, you merge manually after both sessions complete.
• The decision rule: Single complex task with internal parallelism? Use subagents. Multiple independent tasks? Use parallel agents. Very large multi-agent fleet? Consider Claude Dispatch.

What Are the Best Use Cases for Claude Code Subagents?

Subagents outperform single-agent execution when a task genuinely has multiple parallel workstreams that can run simultaneously and produce outputs worth synthesising. The pattern adds overhead; it only pays off when that overhead is justified by the task complexity.

Use these examples to identify matching tasks in your own backlog.

• Full feature implementation: Orchestrator receives "implement user notifications." Subagents run in parallel: API endpoints, schema changes, unit test suite, and API documentation. Orchestrator synthesises into a coherent commit.
• Codebase-wide refactoring: Orchestrator receives "migrate all endpoints to the new error handling pattern." Subagents each handle a separate module. Orchestrator ensures consistency across all outputs.
• Automated PR review workflow: Orchestrator receives the PR diff and spawns subagents for security review, logic correctness, style conformance, and test coverage. Orchestrator compiles one structured review comment.
• Multi-environment validation: Orchestrator receives "validate the build across all target environments." Subagents each run the test suite against a different environment configuration. Orchestrator compiles the compatibility matrix.
• Enterprise-scale development workflows: Large codebases with multiple services benefit most from subagent orchestration. The coordination overhead is justified when the task genuinely spans independent service domains.

Conclusion

Subagents are the right tool when a task is genuinely too complex for a single sequential prompt, not just when a task is large.

The orchestrator/subagent pattern introduces real coordination overhead. It pays off when the internal parallelism is real, the subtask boundaries are clean, and the synthesis step produces something better than any single agent would.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Want Help Architecting a Multi-Agent System with Claude Code?

Designing a subagent system that actually works in production means getting three things right: orchestrator prompt design, permission models, and synthesis strategy. Most teams get one of the three right on the first attempt.

At LowCode Agency, we are a strategic product team, not a dev shop. We design Claude Code orchestration systems that handle genuinely complex development workflows, with the right structure to produce reliable output at scale.

• Orchestrator prompt design: We write the decomposition and synthesis instructions that determine whether your subagent system produces coherent output or fragmented pieces.
• Subagent task scoping: We define clean subtask boundaries so outputs do not overlap and synthesis is straightforward.
• Permission model configuration: We set up CLAUDE.md rules and tool restrictions so each subagent has exactly the access its subtask requires.
• Failure handling strategy: We specify what the orchestrator does when a subagent fails, so your system degrades gracefully rather than silently producing incomplete results.
• MCP integration: We configure external service connections for subagents that need database, API, or third-party tool access.
• AI agent development: We build full multi-agent systems, from single orchestrators to hierarchical agent fleets, scoped to your specific development workflow.
• Architecture review: We evaluate your existing Claude Code setup and identify where subagent orchestration would improve output quality and reduce execution time.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want to build a Claude Code subagent system that handles complex workflows reliably, discuss your project requirements.