How to Use Claude Code Subagents to Run Parallel Tasks

I’ve used Claude Code subagents daily for the past few months. They are what made Claude Code scale for me: several tasks running at once, without my main session losing the thread.

Here is how they work and when I reach for one.

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 keeps its context clean while the child does the digging in isolation.

The subagent starts with zero context from your conversation. It doesn’t know what you’ve been working on or what you already tried. You brief it like a colleague who just walked into the room. That is deliberate, and it is what keeps the two sessions from polluting each other.

When to Use Subagents vs Doing It Yourself

Not everything needs a subagent. Roughly how I split it:

Use a subagent when:

• You need to explore a large codebase and don’t know where things live yet
• Two or more research tasks can run at the same time without touching each other
• The work needs isolation, a separate git worktree for instance
• The search results would be noisy enough to crowd out your main context

Just do it yourself when:

• You already know the target file and what to change
• It’s a three-line edit
• The task depends on something you learned five minutes ago in this conversation
• The call needs judgment, and judgment needs the full context

The threshold I use is whether I’d have to context-switch to do it myself. If I would, I spawn a subagent.

Practical Example: Parallel Code Review

Say you have a PR with changes across the backend, frontend, and test suite. Instead of reviewing it in sequence, you spawn three subagents, each looking at a different dimension of the same diff.

I 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 with no context bleed between them, so the security reviewer never sees the performance opinions.

Practical Example: Research Then Implement

Some subagent work is sequential. Research first, then act on the findings.

Say you need to migrate off 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 reads its way through the codebase and comes back with 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 the full picture sits in your main context. You do the migration yourself, file by file, and let the research set the order: hot-path middleware first, then the workers, then the tests.

I delegate the exploration and keep the implementation. That is how I handle most refactoring work.

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.

Put everything in the background and you end up with results arriving out of order, which you then can’t act on. Put everything in the foreground and you sit there waiting for no reason.

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 and Sentry error fixers. What I’ve learned so far:

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.” Give it the file path and the line, and say what should be different afterwards.

2. Don’t over-delegate. Spawning a subagent costs something: context initialization and result synthesis. For a three-line fix, just do it. Subagents earn that cost on work that would otherwise pollute your context, or on work that runs in parallel.

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

The same pattern shows up outside Claude Code too. In my setup with OpenClaw, the main agent hands specialized work to coding agents and review agents. Each one runs in its own session with its own context, and results flow back automatically.

The Claude Code subagent is the smallest unit of that: one agent, one scoped task. If you’re building autonomous workflows, scheduled jobs or error-fixing pipelines, subagents are how you split the work without losing the thread.

I share operator notes and templates in Build & Automate, where I write up what is running in production for me.

Related Reading

• Run a Claude Code Agent in Production: How to run Claude Code as a real production agent, with 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.