The difference between using one AI coding agent and using five isn’t 5x speed. It’s a different way of working entirely. Instead of one agent doing everything sequentially, you split work across agents that each handle a distinct slice. They coordinate through the filesystem, not through messages.
At HOAi, we’ve been running parallel Claude Code agents as part of our daily engineering workflow. This guide covers the principles we’ve learned. They apply whether you use the CLI, Conductor, or any other tool that supports multiple sessions.
Isolate work with worktrees
The core unit of parallel work is the git worktree. A worktree is an isolated checkout of the repo on its own branch. Each worktree has its own working directory, so agents in different worktrees never step on each other’s files.
The mental model: one worktree per unit of work. That unit might produce one PR or several. A worktree might have one agent or three. The point is isolation. Work in one worktree doesn’t interfere with work in another.
You also get parallelism across worktrees. Agent A works on the settings page in worktree 1, agent B works on the notification service in worktree 2. Completely independent, no coordination needed.
For full isolation, run each worktree inside its own Docker container or local cluster so each agent has its own backend, database, and no port conflicts. Every worktree becomes a self-contained dev environment where agents can run tests, start servers, and iterate without stepping on each other.
Multiple agents per worktree
Within a single worktree, you can run multiple Claude Code sessions simultaneously. They share the filesystem and see each other’s changes in real time. Agent A writes the controller while agent B writes the tests. When A saves a file, B can read it immediately.
This is the higher-leverage form of parallelism. Instead of one agent doing everything sequentially, you split the work across 2-3 agents that each handle a different slice.
For task coordination, use the filesystem as a lock. Anthropic’s engineering team used this pattern when building a C compiler with parallel agents: agents claim tasks by writing a file to a current_tasks/ directory (e.g., current_tasks/parse_if_statement.txt), do the work, then remove the file when done. Any agent can check what’s claimed before picking up new work. No orchestration layer needed.
Sequential dependencies don’t block this either. If agent B needs agent A’s schema before it can finish, agent B can still start on scaffolding, types, and tests while A works. When A writes the schema to disk, B picks it up naturally.
Clear ownership per agent
Before spinning up parallel agents, check one thing: can you describe each agent’s job in one sentence? If the scope is fuzzy (“help with the backend”), the agents will thrash.
If you need complex coordination rules between agents, the decomposition is wrong. Redraw the boundaries so each agent owns a distinct slice.
Spec first, then delegate
Most agent failures come from unclear instructions, not execution failures. The pattern that works:
- Design what you’re building. Think through the problem, challenge your premises, pick an approach.
- Challenge the scope. Ask whether you’re thinking big enough, or whether you should cut to the essentials.
- Lock in the architecture. Nail down data flow, edge cases, and file-level details.
- Implement with parallel agents. Now you have a clear spec. Break it into parallel tasks, each with a focused slice.
The specificity of your spec determines the quality of your agents’ output.
Track progress on disk
Give agents a progress file (a markdown file in the repo) that they read at the start and update as they go. The file survives context compaction because it’s on disk, not in memory.
Claude Code auto-compacts conversation history during long sessions. When compaction happens, the agent re-reads the progress file and picks up where it left off. If an agent loses track of what it was doing, that’s a sign it didn’t have a progress file.
Let tools manage notifications
Don’t poll agents manually. Use a tool that notifies you when an agent finishes or needs input. Whether that’s Conductor’s GUI, cmux for the CLI, or another multiplexer. You should be working on something else while agents run and get pinged when they need you.
Persist context in the codebase
A lot of context gets lost when a session ends. The diff survives, but the reasoning behind it doesn’t.
Commit decision logs. When you make a non-obvious choice (why this approach over that one, what tradeoffs you accepted), write it down. Future agents and future you will need this context when maintaining or extending the work.
Commit plans. If you designed the work before implementing, commit the output. These plans become part of the codebase’s institutional memory. When a new agent picks up related work months later, it can read the plan instead of reverse-engineering intent from the code.
Review the diff, not the conversation. When an agent finishes, look at what it changed. The diff is the deliverable. But make sure the “why” behind the diff is captured somewhere durable.
Getting started
If you’re new to parallel agents, start with two worktrees on independent tasks. Get comfortable with the flow before adding agents within a worktree. The jump from one agent to two is bigger than the jump from two to five, because the first jump changes how you think about decomposing work.
The real skill isn’t running agents. It’s breaking work into pieces that agents can own independently. Get that right and the parallelism follows naturally.