Subagent

A subagent is an autonomous AI entity, a specialized worker you delegate a self-contained job to. Think of it as hiring a contractor for a specific, heavy-lifting task. In environments like Claude Code, when your main agent faces a complex problem requiring deep research, extensive data processing, or intricate reasoning, you hand that specific problem off. This subagent operates within its own fresh, isolated context window. It gets its own tokens, temporary memory, and execution loop. It dives deep into its assigned task, potentially using its own tools, skills, or external systems, all without burdening the main agent's context. Once complete, it returns only the distilled result or a concise summary. This mechanism keeps your primary conversation thread lean, focused, and efficient, preventing the main context window from bloating with subtask minutiae. It is the ultimate token management strategy for large, multi-faceted projects, ensuring the main AI stays on track while specialized components handle the heavy lifting. For a large task, nothing else frees up as much room.

A subagent is not a simple function call or an API wrapper; it possesses its own reasoning and planning, executing tasks with autonomy. It is not a shared memory space; its context is strictly isolated from the main agent's, meaning it does not directly inherit or modify the main conversation history beyond its explicit input and output. It is distinct from a "skill" or "tool" in Claude Code, though a subagent might orchestrate multiple skills. A skill provides a specific capability; a subagent orchestrates a task. It is not a passive memory store like CLAUDE.md. A subagent is an active executor. Furthermore, it is not a magic bullet for poorly defined problems; if instructions are ambiguous, it will struggle. It demands a well-scoped problem definition. It also does not replace fundamental context management like /clear or /compact for the main thread; it complements them by offloading specific burdens.

Consider "PixelForge," a design agency, redesigning an e-commerce platform for "ArtisanBakes." The main Claude Code agent focuses on user experience design for the checkout flow: wireframing, interaction design, user psychology. However, checkout demands complex payment gateway integrations, international shipping logistics, and sales tax compliance across multiple US states. If the main agent had to research all of Stripe's API documentation, parse FedEx's international shipping tariffs for baked goods, and sift through California, New York, and Texas sales tax laws, its context window would explode. It would become slow, expensive, and lose focus on core design.

Subagents solve this. PixelForge delegates these specific, self-contained problems: 1. **Payment Integration Subagent**: Tasked with "Research Stripe's latest API for subscription billing, identify relevant webhooks for failed payments, and draft a concise JSON schema for creating payment intents, noting PCI compliance." This subagent operates in its own isolated context, browsing Stripe's developer docs, consulting security best practices, and returning structured JSON and a webhook summary. 2. **Shipping Logistics Subagent**: Assigned "Analyze FedEx and DHL international shipping rates for perishable baked goods to Canada, UK, and Australia. Factor in customs declarations for food items and provide a cost matrix with estimated delivery times." This subagent uses web browsing tools, parses PDF rate sheets, and returns a clear data table. 3. **Tax Compliance Subagent**: Instructed to "Determine sales tax implications for online sales of baked goods in California, New York, and Texas. Distinguish between physical and digital products if applicable, and summarize state-specific tax rates and reporting frequencies." This subagent focuses solely on tax codes, returning a bulleted list of rates and requirements.

The main agent, focused on checkout UX, receives three clean, processed outputs. Its context window remains dedicated to design principles, user journeys, and visual layouts. It never sees raw API docs, shipping tariff PDFs, or full tax codes. This modular approach allows PixelForge to manage complexity, save tokens, and ensure each specialized task is handled by an AI with a perfectly tailored, uncluttered context, leading to efficient and accurate design for ArtisanBakes.

**When to use a subagent:** * **Heavy lifting and deep dives**: When a task requires extensive research, parsing large documents, complex data analysis, or intricate reasoning that would bloat your main agent's context. For example, if "Brainy Papers" needs to audit 50 academic papers for citation consistency and reformat them to APA 7th edition, a subagent can handle each paper individually, returning only the corrected citations. * **Isolation of concerns**: To prevent detailed, noisy information from polluting the main conversation. If your main agent designs a UI, it does not need raw database query output or full API logs. A subagent processes that data and returns a summary. * **Modularity and decomposition**: For breaking down a large, multi-faceted problem into smaller, manageable, independent components. Think microservices for AI workflows. * **Token efficiency and cost savings**: Offloading context-heavy subtasks keeps the main agent's context lean, leading to faster processing and lower costs. * **Specialization**: When a subtask benefits from a dedicated "persona," specific tools, or unique instructions the main agent does not need. For instance, a subagent could be a "legal researcher" while the main agent is a "marketing strategist."

**When not to use a subagent:** * **Trivial or simple tasks**: For quick operations not requiring significant context or complex reasoning. The overhead of spawning, instructing, and integrating a subagent might outweigh benefits. Asking a subagent to "summarize the last three turns of conversation" is overkill when /compact with instructions suffices. * **Highly interdependent or real-time tasks**: If the subtask requires constant, dynamic back-and-forth or deep, real-time understanding of the main agent's rapidly evolving context, isolation becomes a hindrance. Communication overhead negates benefits. * **Small overall context**: If the entire task is small enough for the main agent to handle all necessary context without hitting limits, subagents add unnecessary complexity without clear gain. * **Over-engineering**: Do not introduce a subagent just because it exists. Use it only when there is a clear problem it solves, typically related to context bloat, complexity, or specialization. * **As a replacement for clear instructions**: A subagent still needs a well-defined task. Vague instructions lead to vague results.

A subagent is your AI contractor: hand it a self-contained problem, and it returns a solution, keeping your main workspace clean and focused.