How to Use Claude Code Subagents to Run Parallel Tasks

I’ve been using Claude Code subagents daily for the past few months. They’re the feature that turned Claude Code from a useful assistant into something that actually scales — running multiple tasks at once without losing context or focus.

Here’s how they work, when to reach for them, and the patterns that actually matter in practice.

What Claude Code Subagents Are

A subagent is a separate Claude Code instance that your main session spawns to handle a scoped task. The parent agent keeps its context clean while the child does focused work — exploring files, running searches, reviewing code, or building features in isolation.

The key thing to understand: the subagent starts with zero context from your conversation. It doesn’t know what you’ve been working on, what files you’ve read, or what you’ve tried. You have to brief it like a colleague who just walked into the room. This is by design — it keeps both agents focused and prevents context pollution.

When to Use Subagents vs Doing It Yourself

Not everything needs a subagent. Here’s the decision framework I use:

Use a subagent when:

• You need to explore a large codebase and don’t know where things are yet
• You have independent research tasks that can run in parallel
• The work needs isolation (a separate git worktree, for example)
• You want to protect your main context from noisy search results

Just do it yourself when:

• You already know the target file and what to change
• It’s a simple edit — three lines of code don’t need a subagent
• The task depends on something you just learned in this conversation
• You need to make a judgment call that requires full context

The threshold is roughly: if you’d context-switch to do it, spawn a subagent. If you’d just do it inline, do it inline.

Practical Example: Parallel Code Review

This is where subagents shine. Say you have a PR with changes across the backend, frontend, and test suite. Instead of reviewing everything sequentially, you spawn three subagents — each reviewing a different dimension of the same PR.

Here’s what that looks like in practice. You tell Claude Code something like:

Review this PR for security issues, performance concerns, and test coverage gaps. Run all three reviews in parallel.

Claude Code spawns three subagents simultaneously:

1. Security reviewer — checks for injection vulnerabilities, auth bypasses, exposed secrets, unsafe input handling
2. Performance reviewer — looks for N+1 queries, missing indexes, unnecessary re-renders, large payload sizes
3. Test coverage reviewer — identifies untested code paths, missing edge cases, brittle test patterns

Each subagent gets a self-contained prompt with the PR diff and a specific focus area. They run concurrently, so a review that would take 15 minutes sequentially finishes in 5.

When all three return, you get three focused reports. No context bleed between them — the security reviewer isn’t distracted by performance opinions, and vice versa.

Practical Example: Research Then Implement

Not all subagent work is parallel. Sometimes you need a sequential pattern: research first, then act on the findings.

Say you need to migrate from a deprecated API across your codebase. You don’t know how many call sites exist or what patterns they use. The approach:

Step 1: Spawn a research subagent to find every usage of the deprecated API. Give it a clear brief:

Find all usages of the legacyAuth.verify() method across the codebase. For each usage, note the file, the surrounding context, and whether it’s in a hot path or a background job. Report back with a summary.

The subagent explores, searches, reads files, and returns a structured report: “Found 12 usages across 8 files. 3 are in request middleware (hot path), 5 are in background workers, 4 are in tests.”

Step 2: Now you have the full picture in your main context. You implement the migration yourself, file by file, using the research to prioritize: fix the hot-path middleware first, then the workers, then update the tests.

This pattern — delegate the exploration, keep the implementation — is how I handle most refactoring tasks.

Running Subagents in the Background

Claude Code gives you two modes for subagents: foreground and background.

Foreground (default): You wait for the result before doing anything else. Use this when the subagent’s output determines your next step — like the research-then-implement pattern above.

Background: The subagent runs independently and you get notified when it’s done. Use this for genuinely parallel work where you don’t need the result immediately.

The distinction matters. If you put everything in the background, you’ll end up with results you can’t act on because they arrived out of order. If you put everything in the foreground, you’re waiting unnecessarily.

My rule of thumb: if I’m going to read the result and then decide what to do, foreground. If I already know what I’m doing and the subagent is handling something separate, background.

Tips From Running Subagents in Production

I run subagents as part of an autonomous agent system — scheduled cron jobs, code review bots, Sentry error fixers. Here’s what I’ve learned:

1. Write self-contained prompts. The subagent has zero context from your conversation. Don’t say “fix the bug we discussed” — say “fix the null reference error in src/auth/middleware.ts at line 47 where user.email is accessed before the null check.” Include file paths, line numbers, and what specifically needs to change.

2. Don’t over-delegate. Spawning a subagent has overhead — context initialization, prompt processing, result synthesis. For a three-line fix, just do it. Subagents earn their cost on tasks that would pollute your context or benefit from parallelism.

3. Use worktree isolation for code changes. When a subagent needs to modify files, give it a git worktree so it works on an isolated copy. This prevents conflicts with your main working tree and makes it safe to run multiple coding subagents in parallel.

4. Limit parallel spawns. Three to five concurrent subagents is the sweet spot. Beyond that, you’re juggling too many results and the synthesis overhead cancels out the time savings.

5. Trust the push-based completion model. Don’t poll for subagent status. You get notified when they’re done. Polling wastes cycles and adds noise.

How This Fits Into Larger Agent Architectures

Subagents aren’t just a Claude Code feature — they’re a pattern. In my setup with OpenClaw, the main agent delegates specialized work to coding agents, research agents, and review agents. Each one operates in its own session with its own context, and results flow back automatically.

The Claude Code subagent model is the smallest unit of this pattern: one agent, scoped task, clean handoff. If you’re building autonomous workflows — scheduled jobs, error-fixing pipelines, multi-repo operations — subagents are how you decompose the work without losing coherence.

If you’re building agent workflows like this, I share operator notes and templates in Build & Automate — the community where I break down what’s actually working in production.

Related Reading

• Run a Claude Code Agent in Production — How to run Claude Code as a real production agent — observability, retries, secrets, drift handling.
• Give Claude Code Agents Real Autonomy — Letting Claude Code take action on its own without 3 a.m. surprises.
• Write Claude Code Agent Skills That Actually Work — Custom skills that consistently fire and produce useful output.