One of my students shared their screen last week, proud, a little sheepish.
Eight terminal windows. Eight Claude Code agents running simultaneously, each one generating code at a steady clip. Color-coded tabs. It was genuinely impressive to look at.
"Okay," I said. "What is each one doing?"
The pause that followed went on longer than it should have. Three of the agents, it turned out, were all editing the same authentication module. Two had made conflicting changes that neither had noticed. One had introduced a bug while fixing a bug introduced by another. The whole thing had become a cascade of well-intentioned AI mistakes, each one building confidently on the last.
We spent the next hour unraveling it.
Table of Contents#
- The myth that more agents means more output
- What I mean when I say management
- Why more agents can make things actively worse
- The approach that actually works
- Use git worktrees for true isolation
- Your codebase determines whether agents succeed
- Context-switching is the actual job
- What productive multi-agent work actually looks like
- A practical progression
- FAQ
The myth that more agents means more output#
This is the most common thing I see in students right now. Not laziness. Not a lack of effort. The opposite.
They work hard to set up the most elaborate multi-agent Claude Code workflows they can, because somewhere they read that running ten agents at once is what the top developers are doing. They see the screenshots. The six IDE windows. The parallel terminals. It looks like leverage.
They are not wrong that the best practitioners run multiple agents. But they have skipped something important.
Before you can run many agents productively, you need to understand one agent deeply. And before that, you need to understand what the actual skill is.
It is not prompting. It is not configuration. It is not even knowing which model to use.
It is management.
What I mean when I say management#
When you run two Claude Code agents simultaneously, you become a manager. Not metaphorically. In a very real, operational sense.
You are tracking what two entities are doing at the same time. You are deciding when to intervene, when to let them continue, when to redirect them toward a different approach. You are checking their outputs, noticing conflicts, resolving disagreements between their versions of reality. You are also deciding which tasks to give each one, making sure their work does not overlap, making sure they have what they need to proceed without blocking each other.
The developers who do this well, the ones who can run four or five agents without the system collapsing, often share a surprising background. They have managed humans before. They understand what it feels like to track parallel workstreams. They know that "I will just let it run" is not a management strategy. They have developed the instinct to check in at the right intervals, to notice when something is drifting before it compounds into something much harder to fix.
If you have never managed a team, multi-agent orchestration will teach you why management is hard. Not through reading about it. Through watching your agents slowly contradict each other while you were not paying attention.
This is actually good news for students who have had some experience coordinating people, even informally. Running a project with a few collaborators, managing a small team at a previous job, even coordinating a group assignment with clear task ownership: all of that builds instincts that transfer directly to multi-agent work.
For everyone else, those instincts develop through practice. But you need to practice them deliberately, not by opening ten terminals and hoping.
Why more agents can make things actively worse#
Here is the part nobody explains clearly. Adding a second agent does not just add one more thing to monitor. It adds a new surface area for errors to compound.
Suppose agent A makes a small wrong assumption in how it models your database schema. Agent B does not know this. Agent B writes migration code that assumes the schema is correct. Now you have two layers of mistake, each one confident and well-formatted. Add a third agent working on the API layer, and it too builds on the wrong foundation. By the time you catch it, you are not debugging one error. You are debugging three interlocked ones, each of which made perfect sense given the context each agent had.
This is not a hypothetical. It is what my student's eight-window setup had produced. The agents were not broken. They were working exactly as designed. The problem was that they were working in parallel on overlapping concerns without any mechanism to coordinate their assumptions.
Spaghetti code does not emerge from bad agents. It emerges from unsupervised agents. The same way spaghetti processes emerge from unsupervised teams. More agents without more oversight is not a multiplier. It is a risk amplifier.
The confidence of AI-generated output makes this worse, not better. The code looks clean. The commit messages are descriptive. The tests pass in isolation. Everything signals correctness right up until the moment you try to run the whole system together.
If you have been building production multi-agent systems as I have, this pattern is familiar. I wrote about it in detail in Building Production-Ready Multi-Agent Systems, and the core lesson there still holds: the hardest bugs in agent-driven development are not single-agent bugs. They are coordination bugs that no individual agent could have caught on its own.
The approach that actually works#
Here is what I now tell students who come to me with eight terminal windows and a problem.
Start with one agent. Not one agent in a ten-agent setup, not one agent as a stepping stone to spin up nine more by the end of the session. Just one. Give it a meaningful, non-trivial task. Watch how it handles edge cases, how it responds when the code does not do what it expected, how it behaves when the context gets complicated. Get genuinely comfortable with that single agent's patterns and failure modes.
When you feel confident in how it performs, not just in one happy-path scenario but in situations where things go slightly sideways, then look for a second task. And be specific about what "a second task" means here. It needs to be isolated. It should not share files with what the first agent is doing. It should not depend on assumptions the first agent is forming. Think: one agent is adding a new API endpoint, the other is updating the README. These tasks have no intersection. They cannot conflict.
Then watch both. Switch your attention deliberately, not randomly. Check in on each agent before it has gone too far down a wrong path. Learn what "too far" looks like for your specific codebase.
When that feels manageable, consider a third.
This is slower than opening ten terminals on day one. It is supposed to be. You are building a skill, not completing a benchmark. The students who develop genuine multi-agent fluency do it this way. The students who open ten windows on day one spend most of their time cleaning up instead of building.
Use git worktrees for true isolation#
There is a tool that solves the file-conflict problem at the git level, and most students have never heard of it. Git worktrees let you check out multiple branches of the same repository into separate directories simultaneously, each one a fully independent working copy.
When you give each Claude Code agent its own worktree, they literally cannot edit the same file at the same time. They are working in separate directories on separate branches. The isolation you are trying to enforce through careful task assignment becomes structural rather than a matter of discipline.
The setup is straightforward. From your project root:
git worktree add ../my-project-agent-2 -b agent/feature-x
git worktree add ../my-project-agent-3 -b agent/tests
Now you open one Claude Code session in ../my-project-agent-2 and another in ../my-project-agent-3. Each agent has its own branch, its own working directory, its own files. They are running on the same codebase but completely cannot interfere with each other.
When an agent finishes its task, you review the branch, merge it if it looks good, and remove the worktree:
git worktree remove ../my-project-agent-2
This is the pattern I teach first now, before multi-agent anything. If you are not using worktrees, you are relying on task discipline to prevent conflicts. Task discipline fails. Git worktrees do not.
The other thing worktrees give you is a clean history. Each agent's work lives on its own branch. You can see exactly what it did, diff it against main, and make a deliberate decision about whether to keep it. Compare that to three agents all writing to the same branch: the history is tangled, the conflicts are hidden in merge commits, and figuring out which agent introduced a specific change becomes an archaeology project.
Claude Code has built-in worktree support via the /worktree command, which makes this even easier. Before you spin up a second agent, run /worktree in your Claude Code session and let it create the isolated environment for you.
Your codebase determines whether agents succeed#
Here is something I find genuinely underappreciated in the conversation about multi-agent Claude Code workflows. The agents do not fail because of the agents. They often fail because of the codebase.
Your codebase is either agent-friendly or it is not. And most codebases, even good ones built by careful engineers, are not particularly agent-friendly. There are three things that make the biggest practical difference.
Test coverage. Your tests are the contracts that agents operate on. Without adequate test coverage, an agent has no mechanism to verify its own work. It writes code, nothing tells it the code is wrong, and it moves on. You discover the problem later, after more has been built on top of it. If you released a Claude Code agent into your codebase right now, would it know what "working" looks like? If the answer is uncertain, you need more tests before you need more agents.
README and documentation accuracy. Every developer knows that READMEs get out of date. The code says one thing, the documentation says something different from six months ago. For a human developer this is annoying but manageable. They can ask a colleague. For an agent, this is a forced choice with no good information to go on. It has to pick which source of truth to believe. It will pick wrong sometimes, and it will not know it picked wrong. Keeping your documentation current is not glamorous work. But it eliminates an entire category of agent confusion that otherwise has to be debugged by hand.
Design pattern consistency. If one part of your codebase creates objects using one pattern, and another part uses a completely different pattern for the same thing, which should an agent follow? A new human developer would ask someone. An agent will pick one and build on it, sometimes the worse choice, sometimes introducing a third pattern that compounds the inconsistency. Agents can infer and follow clear, consistent conventions. In a codebase that has accumulated different approaches over years, they will reflect that inconsistency back at you, amplified.
The most productive thing you can do before adding a second agent is make sure your first agent has a clean, self-consistent codebase to work in. Not perfect. Consistent.
If you are using Claude Code plugins as part of your workflow, a few of them help with exactly this. I covered the ones I have found most useful in 5 Claude Code Plugins That Actually Changed How I Build.
Context-switching is the actual job#
When you have two agents running, you are watching two terminal windows. When you have three, you have three. At some point, and for most people this is around four or five, you hit a natural limit. You cannot track everything. Things fall through.
The context-switching between agents is the hardest part of multi-agent orchestration. It is also the part that develops most clearly with practice.
You are building a mental model of where each agent is in its task. What decisions has it made? What files has it touched? What assumptions is it currently operating on? You need to hold multiple versions of this mental model simultaneously, update them as you check in on each agent, and notice when something in one model conflicts with something in another.
This is exactly what managers do with human direct reports. The skill is not heroic multitasking. It is closer to spatial reasoning: the ability to maintain a clear picture of multiple parallel workstreams without losing the thread of any of them. And like spatial reasoning, it gets better with practice if you practice it deliberately.
What does deliberate practice look like? Start by checking in on each agent at fixed intervals. Every ten minutes, switch your attention. Review what the current agent has done, assess whether it needs correction, note where it is headed, then move to the next. This feels mechanical at first. That is fine. The mechanical cadence helps you build the habit before you develop the instinct.
Over time, you stop needing the fixed intervals. You develop a sense for when an agent is about to go sideways, based on the direction of its recent decisions. That sense is the real skill. And you cannot develop it by watching ten agents at once. You develop it by watching one or two, carefully, for long enough that the patterns become recognizable.
What productive multi-agent work actually looks like#
When it works, it looks surprisingly quiet.
One agent is refactoring a module. You have reviewed its approach, you understand what it is trying to do, and it is making steady sensible progress. You check in, verify it has not drifted, and shift your attention.
The second agent is writing tests for a feature you shipped last week. You watch it work for a few minutes. It is covering the happy path well. You notice it has not yet addressed one edge case. You make a note, not an immediate intervention, just a note. You will check back.
You are not watching both simultaneously. You are shifting your attention deliberately, maintaining awareness of both, intervening when necessary rather than constantly. That is the whole skill. Not the setup. Not the tooling configuration. The deliberate attention management that keeps a multi-agent system from becoming a multi-agent mess.
The students who get to this point tend to describe it the same way: calmer than they expected. The chaos of their early experiments gave way to something that feels more like conducting than firefighting.
There is also a quality dimension worth naming. The best practitioners are not the ones who hit the minimum viable output and move on. They are the ones who keep iterating after the requirements are technically met. One more pass on the edge case. One more look at whether the agent's choice was actually the best choice or just a reasonable one. That extra attention is where taste develops, and taste is what separates functional code from code you are proud of. Agents can do a lot, but the judgment about whether something is genuinely good still sits with you.
A practical progression#
If I were starting with multi-agent Claude Code from zero today, here is how I would build up to it.
First, get deeply comfortable with single-agent workflows on a real project. Not a toy. Something where the requirements are ambiguous, the codebase has rough edges, and mistakes have actual consequences. Understand how the agent handles unclear instructions, what it does when it encounters inconsistencies, where it tends to go wrong. This foundation alone will make you more productive than most developers using agents.
When single-agent work feels natural, identify one task in your project that is completely isolated from your main work. No shared files, no shared context, no dependencies on what your primary agent is doing. Spin up a second agent for only that task. Practice switching your attention between them. Notice what is different about tracking two things instead of one.
After a few sessions like this, step back and look at your codebase. Is your test coverage good enough that agents can verify their own work? Is your documentation accurate? Are your design patterns consistent enough that an agent can infer which one to follow? Fix the worst offenders before adding more agents.
Then, gradually, add more. But only when the previous level feels genuinely manageable. The right number of agents is not the maximum you can configure. It is the maximum you can actually orchestrate without losing track of what each one is doing.
FAQ#
How many Claude Code agents should I run as a beginner?#
One. Get genuinely comfortable with it on a real project before considering a second. Most of the meaningful productivity gains from multi-agent Claude Code come from running two or three well-orchestrated agents, not from maximizing the number of terminals you have open.
What makes a task suitable for a separate agent?#
The task should be isolated. It should not share files, context, or assumptions with what your other agents are working on. Good candidates: updating documentation, writing tests for an already-shipped feature, building a standalone UI component. Poor candidates: anything that touches files or modules your other agents are also editing.
Why do agents compound each other's errors?#
Each agent builds on the context it has, which includes work done by other agents. If one agent makes a wrong assumption and another agent does not know this, the second agent will build on that assumption. The error does not cancel out. It accumulates. This is why careful oversight becomes more important as you add agents, not less.
Does my codebase need to be perfect before I use agents?#
No. But it needs to be self-consistent. Tests should reflect what the code actually does. Documentation should match current behavior. Design patterns should be consistent enough that an agent can infer which one to follow. You do not need a perfect codebase. You need one that is not actively giving agents contradictory signals.
What are git worktrees and why do they matter for multi-agent Claude Code?#
Git worktrees let you check out multiple branches of a repo into separate directories simultaneously. Each agent gets its own directory and its own branch, so they physically cannot edit the same files. It is the most reliable way to enforce isolation. Claude Code supports this natively via the /worktree command.
How do I handle conflicts when two agents edit the same file?#
Use git worktrees to prevent this structurally before it happens. If you are not using worktrees, assign agents to genuinely non-overlapping work. When conflicts happen anyway, resolve them yourself. Do not ask a third agent to adjudicate between two conflicting agents. That adds another layer to an already complicated situation and rarely produces the right answer.
I am a junior developer. Should I even be trying multi-agent workflows?#
Yes, and you may actually adapt to this faster than more senior developers. Junior developers have not yet built rigid habits around how software development is supposed to work. That makes it easier to develop new instincts. The one thing I would emphasize: build a solid foundation in programming fundamentals first. Understanding how to decompose a system, trace a bug, and reason about code behavior matters more in an agent-driven workflow, not less. Agents do not replace that thinking. They require it.
How do I know when I am ready to add another agent?#
When the current setup feels boring. When you are not constantly intervening, not constantly catching mistakes, not constantly losing track of where each agent is. Boredom in a good multi-agent setup is a signal that your current level of complexity is manageable, which means you have capacity for more.
The students I have seen develop genuine multi-agent fluency are not the ones who opened ten windows on day one. They are the ones who started with one agent, learned that deeply, found the edges of it, and built up incrementally, with the same patience a good manager brings to building a team.
Most of my students figure this out eventually. Usually after a session that looks a lot like eight windows of chaos and an hour of cleanup. The lesson does tend to stick better that way.
If you are working through this progression and hitting specific problems, I would like to hear about it. The failure modes I see most in students tend to repeat. Knowing which one you are in makes it much easier to get unstuck.
And if you are ready to go deeper on the production side of multi-agent systems, the architecture patterns in Building Production-Ready Multi-Agent Systems cover what happens once the orchestration is working and you need it to hold up at scale. If you end up using LangGraph to wire your agents together, the LangGraph Deep Dive covers the state machine patterns that make complex workflows actually debuggable.