The thing that changed how I ship was not a smarter model. It was the moment I stopped watching Claude Code work. Background execution and parallel subagents turn a coding agent from a very fast pair programmer you babysit into a small team you dispatch, and the difference in throughput is not 20 percent, it is a different category of work becoming possible. I have used this to build an 854-item prompt library in six parallel waves in a single working session, and to rewrite 84 blog posts across seven batches on this site. Neither project would have happened serially; I would have gotten bored or busy around item forty.
This post is the practical version: what background agents actually are in Claude Code, how I structure parallel waves on real production work, and the specific failure modes I have collected — because parallelism does not remove problems, it multiplies the interesting ones.
The Waiting Problem
A standard agent session is serial: you prompt, the agent works, you wait, you review, you prompt again. For a single feature that loop is fine. The waiting becomes the bottleneck the moment your work has independent parts: a test suite that takes four minutes, a refactor across ten files that do not touch each other, forty database records that each need the same treatment.
Claude Code attacks this from two directions, and it is worth keeping them distinct because they solve different problems:
- Background tasks: a shell command dispatched with
run_in_backgroundkeeps running while the session moves on, and reports back when it exits. This kills the "agent sits idle while the build runs" tax. - Parallel subagents: the session spawns multiple agents, each with its own context window and task, working simultaneously. This kills the "one context window, one job at a time" tax.
Background tasks are the easy win. Long test runs, builds, imports, anything that streams for minutes: dispatch it, keep working, get pinged on exit. The mistake I made early was leaving interactive judgment calls in the background — a task that needs a decision mid-run just stalls out there. The rule I settled on: background anything that is deterministic once started, foreground anything that might need me.
Where Parallel Subagents Actually Earn Their Keep
The honest criterion is independence. Two tasks qualify for parallel execution when neither needs the other's output and they do not write to the same files. That sounds obvious; in practice almost everyone (including past me) discovers a hidden dependency mid-run.
Concrete runs from my own logs, because abstract advice about parallelism is worthless:
The prompt library. 854 prompts on this site needed depth content — real body text and FAQ sections, not filler. Each prompt was fully independent of every other. I split the backlog into six waves of parallel workers, each worker assigned a fixed ID range, each writing its results to its own files. What would have been weeks of serial grinding closed in one long session. The design work was not the writing; it was the partitioning.
The 84-post rewrite. SEO rewrites across seven batches of roughly twelve posts each. Same shape: independent items, fixed assignments per worker, one durable manifest file (REWRITE-STATUS.json) tracking which posts were DONE versus PENDING so any batch could resume after an interruption. That manifest is the unglamorous hero: parallel work without a resume file means one crash re-does or, worse, double-applies work.
Verification waves. After bulk changes, I dispatch reviewer agents in parallel: one checks links, one checks facts against the database, one checks formatting. Reviewers parallelize beautifully because reading never conflicts.
If you want the architectural background on how the orchestrator-and-workers pattern hangs together, I wrote up the full topology in my agent swarm architecture breakdown, and the mechanics of spawning workers with clean context in how forked subagents work.
The Gotchas List, Earned the Slow Way
Everything in this section cost me real time. That is the point of publishing it.
Shared scratch space is a collision waiting to happen. Parallel workers in the same session share temp directories unless you tell them otherwise. I have had one worker overwrite another's intermediate JSON mid-run — same filename, both workers confidently reading data that belonged to the other. It happened again as recently as this week. The fix is boring and absolute: every worker gets a uniquely named working directory or file prefix, no exceptions. Verify what you read back is what you wrote.
Guard your write ranges. When workers apply changes to a database or file set, each worker's apply script gets a hard range guard: refuse to touch any ID outside the assignment. During my 84-post project the guard was the only thing standing between "batch 3 applies batch 3" and a worker with a stale file list quietly clobbering another batch's finished work.
ssh eats your loop. A shell loop like while read id; do ssh server "..."; done silently consumes the rest of your input list through stdin on the first iteration; ssh -n fixes it. I lost a genuinely embarrassing hour to a "loop" that processed exactly one item. Background agents run a lot of shell; the classic shell traps come along for the ride.
Parallel writing needs serial review. The waves generate; a single reviewer pass accepts. Every time I have been tempted to skip the serial review because "the workers all had the same instructions," the merged result contained inconsistencies no individual worker could see: repeated phrasing across items, two workers resolving the same ambiguity opposite ways. Generation parallelizes. Judgment does not.
Isolation beats coordination. When two workstreams must touch the same repo, I stop trying to choreograph them in one working tree and give each its own git worktree. Separate branches, separate directories, merge as the integration point. Every scheme I tried that was cleverer than that was also more broken than that.
The Handoff Is Part of the System
Background and parallel work create a new problem serial sessions never had: state that outlives any single session. A wave finishes at 1 AM; the next session needs to know exactly where things stand without re-deriving it.
Two habits cover this. First, the manifest pattern above: machine-readable status, updated only on verified completion, so "what is done" is a file, not a memory. Second, an explicit handoff note per session: what was completed, what is mid-flight, what the next session must check first. I have refined this into a reusable process — the handoff skill for multi-session work — and it converts "day two of the project" from archaeology into a running start.
For work that recurs rather than resumes (nightly checks, scheduled reports), the background-agent mindset extends naturally into scheduled loops and cron-driven routines, which is the same delegation muscle pointed at the calendar instead of the task list.
A Day With This Workflow
What it looks like in practice, without romance. I start a session by dispatching the long stuff: test suite in the background, any bulk wave whose assignments I prepared the evening before. Foreground goes to the work that needs my judgment — design decisions, reviews of yesterday's wave, the one gnarly bug that resists delegation. Notifications from background tasks land as they finish; I triage instead of poll.
The measurable change is not typing speed. It is that the expensive resource — my attention — stops being chained to the cheap one, elapsed compute time. On a solo project that is nice. Across a client portfolio and a 500-plus-post platform, it is the difference between maintenance being possible and not. After 8+ years and 1,500+ projects of doing this the serial way, the parallel version is the first workflow change I would genuinely call structural.
Start Smaller Than You Want To
The failure mode for newcomers is dispatching five parallel agents on day one and drowning in unreviewed output. Sequence it: first, background one long-running command and keep working, to build the trust that the ping comes. Second, run two independent tasks in parallel with explicitly separated files. Third, try a real wave with a manifest and range guards. Each step teaches you the supervision instincts the next one assumes.
Several of the automation skills I publish exist because a parallel wave taught me the partitioning rule the expensive way: clean assignments, no shared state, verified completion. They sit on my agent skills marketplace, and reading one apart teaches more than running it blind.
