Late November last year I was three weeks into a WooCommerce build for a wholesale client. Thirty-odd custom post types, a bespoke pricing engine, and a checkout flow that had more conditional logic than I care to remember. I was the only developer on it. And I was losing days just context-switching between the plugin layer, the theme overrides, and the REST API endpoints.
That's when I properly committed to running Claude Code subagents in parallel. Not dabbling. Actually restructuring how I break down work so multiple agents can move simultaneously without stepping on each other.
Here's what I learned, including where I got it wrong first.
---
What "Subagents" Actually Means in Claude Code
People use the word loosely. In Claude's agentic framework, a subagent is simply a Claude instance that receives a scoped task from an orchestrator, executes it, and returns output. The orchestrator (which can itself be a Claude session) decides how to split the work, which subagents to spin up, and how to combine the results.
In practice, for most of us building sites and applications, this means running multiple terminal sessions, each with a focused Claude Code context, against the same codebase. Sometimes the orchestration is automated via a script. Often, honestly, it's just me manually coordinating what each agent is working on from a planning doc in Notion.
The difference between sequential and parallel
Sequential agentic work is what most developers default to: ask Claude to do task A, wait, then ask it to do task B. Fine for simple stuff. But if A and B don't depend on each other's output, you're leaving time on the table.
Parallel subagents run simultaneously on independent workstreams. The WooCommerce project I mentioned: I had one agent refactoring the pricing engine logic while another was generating PHPDoc comments across the REST API controllers. Zero overlap. Both done in about the time it would have taken to do one.
---
How I Actually Structure the Work Split
This is the part nobody talks about clearly enough. The agent setup is the easy bit. The hard bit is figuring out what to split.
I use a simple rule I came up with after a painful merge conflict incident back in 2022: no two agents should touch the same file during the same session. Full stop. If I can't guarantee that, the tasks don't run in parallel.
My planning step before any parallel run
Before I spin anything up, I write a short task manifest. Nothing fancy, just a plain text file or a Notion page with:
- Task name and a one-sentence description
- Files in scope (explicit list)
- Files out of scope (anything adjacent that might tempt an agent to wander)
- Expected output format
- Any context the agent needs that isn't in the codebase
This takes me maybe 15 minutes. It has saved me from a genuinely embarrassing number of conflicts.
---
The Three Workstream Types I Split Most Often
Over 12,000+ site builds at Seahawk, and my own solo client work on the side, I've noticed the same categories come up repeatedly as good candidates for parallelisation.
1. Documentation and code generation
One agent writes or refactors code. Another writes documentation, tests, or comments for a different module. These almost never conflict and both are genuinely tedious to do manually. On the WooCommerce wholesale project, I had one subagent generating PHPUnit test stubs for the pricing functions while another was building out the custom admin columns. The test stubs took about four minutes. The admin columns took twelve. I lost none of those four minutes waiting.
2. Frontend and backend isolation
If your frontend and backend live in clearly separated directories (which they should, but that's a different post), this is a natural split. I've run a subagent building out React components in /resources/js while another was wiring up Laravel controllers in /app/Http . The only coordination point was agreeing on the API contract before either agent started. I wrote that in a AGENTS.md file at the root of the project. Both agents referenced it.
3. Module-by-module refactoring
Big refactors are miserable when done sequentially. If you have, say, eight feature modules that each need the same type of change (updating a deprecated method, migrating to a new helper, whatever), split them across agents. I once ran four simultaneous agents migrating a legacy plugin from WP_Query loops to a repository pattern. Each agent got two modules. Done in under an hour. Sequentially that was going to be a half-day.
---
Tooling Setup: What I Actually Use
I'm not going to pretend I have some elaborate infrastructure. My actual setup is:
- Claude Code running in multiple
tmuxpanes on a single MacBook Pro M3 - A shared
AGENTS.mdfile in the project root that defines conventions, file ownership, and the API contract between workstreams - Git branches per agent. Always. Even if the branch only lives for twenty minutes
- A quick
git diff --statbefore any merge to catch surprises
The AGENTS.md file is probably the single most useful thing I've added to my workflow in the past year. It's a plain markdown file that tells any agent (or human, for that matter) what the project conventions are, which files belong to which workstream, and what to avoid touching. Think of it like a CONTRIBUTING.md but written for AI context windows.
On context window management
This is where people get lazy and then confused. Each subagent has its own context. That means if Agent B needs to know what Agent A decided, you have to tell it explicitly. It won't just know.
I handle this by keeping a SESSION_LOG.md that I update manually after each agent completes a chunk. It's three to five bullet points max: what was done, what changed, what the next agent needs to know. Overhead is low. The alternative is an agent making assumptions that break your code, and that overhead is much higher.
---
Where It Goes Wrong (From Painful Experience)
Seahawk had a fintech dashboard project last spring where we tried to run subagents across a monorepo without proper file ownership defined. Two agents both decided to update the shared utils/formatters.ts file. Neither knew about the other. The resulting merge was fine, technically, but we spent 40 minutes reconciling intent. Completely avoidable.
The failure modes I see repeatedly:
- Shared utility files. These are a trap. Lock them down. If a subagent needs to update a shared utility, that task should run alone, not in parallel.
- Vague task descriptions. An agent given "clean up the auth module" will interpret that very differently depending on what's in its context. Be specific. "Refactor
AuthController.phpto use theUserRepositoryinterface already defined inapp/Repositories/UserRepository.php. Do not modify the interface itself." That's a safe prompt. - No branch isolation. Running all agents on
mainis how you create exciting Friday afternoons. Branches cost nothing. - Skipping the manifest. I know, I know. It feels like overhead. Do it anyway. Every time I've skipped it I've regretted it within an hour.
---
A Real Parallel Run, Step by Step
Here's roughly what last Tuesday's session looked like for a Shopify-to-WooCommerce migration project (anonymised, but the structure is exact).
- I wrote the task manifest in Notion. Four tasks identified as parallelisable.
- Created four git branches:
agent/product-import,agent/tax-logic,agent/rest-endpoints,agent/admin-ui. - Opened four
tmuxpanes, one Claude Code session each. - Pasted the relevant section of
AGENTS.mdat the start of each session as context. - Gave each agent its task prompt, referencing specific files.
- Ran all four simultaneously. Made a coffee. Actually drank it while it was still hot, which felt like a miracle.
- Reviewed each branch output. Ran
phpcson the PHP,eslinton any JS touched. - Merged in sequence: product import first (the others had light dependencies on its schema), then tax logic, then the REST endpoints, then admin UI.
- Updated
SESSION_LOG.mdwith what changed.
Total time for all four tasks combined: about 35 minutes. My estimate for sequential completion was 90 minutes to 2 hours. I'll take that.
---
What This Does (and Doesn't) Replace
Parallel subagents are not a substitute for thinking. That 15-minute planning step is genuinely you doing the architecture work. The agents execute. You still have to know what to build, how the pieces fit, and whether the output is actually correct.
I review every agent's output before it touches main. Every single time. I've caught a subagent confidently write a caching layer that would have caused stale data issues on a multisite setup. The code looked fine. It was logically wrong for the specific context. Only caught it because I read it.
Anthropic's own guidance on agentic tasks specifically flags the importance of human checkpoints before irreversible actions. That's not corporate boilerplate. It's actually important advice, especially when agents have write access to databases or are running migrations.
The other thing this doesn't replace: communication with clients. An agent can build a feature. It cannot tell a client why a deadline shifted or manage expectations around scope creep. That part is still yours.
---
FAQ
Do I need special API access or tooling to run Claude Code subagents?
No exotic setup required. Claude Code is Anthropic's terminal-based coding tool, and you can run multiple instances in separate terminal sessions (I use tmux). You do need a Claude API key with sufficient rate limits if you're hitting the API directly. For heavy parallel workloads, check your rate limit tier before you start so you don't hit throttling mid-session.
How do I stop agents from conflicting on shared files?
Define file ownership before you start. The AGENTS.md convention I described works well. If two tasks both need a shared utility file changed, don't parallelize those two tasks. Run the shared utility change first, commit it, then run the other tasks in parallel from that clean base.
Is this only useful on large projects?
Honestly, no. I've used it on single-page sites where I wanted documentation generated alongside new feature code. The overhead of planning is low enough that even modest time savings justify it. That said, if a project has fewer than maybe five distinct parallelisable tasks, the setup time starts to outweigh the benefit. Use your judgement.
What happens if an agent produces bad output?
You catch it in review, discard the branch, and try again with a more specific prompt. That's the whole point of branch isolation. Bad agent output costs you the time to review it and re-prompt. It shouldn't cost you a broken codebase if you're following the branch-per-agent rule.
Can I automate the orchestration instead of doing it manually?
Yes, and for repeating workflows it's worth it. I've written simple Bash scripts that spin up sequential Claude Code calls with pre-defined prompts and context. For fully automated parallel orchestration, you'd build an orchestrator layer that programmatically spawns agents, collects output, and handles dependencies. That's a bigger engineering investment. For most freelancers and small agencies, manual coordination with tmux and a task manifest is plenty.
---
The honest truth is that parallel subagents didn't make me a dramatically better developer. They made me a faster one, on the specific class of tasks where the bottleneck was execution rather than thinking. The thinking is still mine. The architecture decisions, the client calls, the code review. All still mine.
But the tedious execution parts? I'll take every minute back that I can get.