Claude Code / Codex Multi-Agent Parallelism: A Division of Labor for Beginners

The most problematic area with multi-agent setups often has little to do with intelligence. The real headache is when 5 agents modify the same batch of files simultaneously. It looks busy, but when you merge, it’s all conflicts, and you still have to clean up the mess.

Note: The illustrations in this article come from my open-source skill: “Juju Content Illustrations Skill”, https://github.com/dososo/juju-content-illustrations

Now Claude Code, Codex, and Gemini CLI all support subagents or parallel agent workflows. The official docs say it directly: these capabilities are good for codebase exploration, multi-step planning, batch review, parallel research, component splitting, and large-scale migrations.

But beginners often misunderstand “parallel” as “let 5 agents edit whatever they want at the same time.” That’s dangerous. The more capable the agent, the faster it can mess up files. One person making a mess is still manageable with git diff; five agents making a mess, and no one will know which change was for what.

A better approach: The main session only does control and validation; each of the 5 agents gets a clear boundary. Read-only when possible; if files must be modified, use separate worktrees. This turns parallelism into efficiency and keeps the project from getting chaotic.

First, Understand: What Tasks Are Suitable for Parallel Agents

Parallel agents are good for tasks that can be split apart with little interdependence. For example, have one agent check the login module, one check the payment module, one check test coverage, one check error logs, and one organize docs. These can run simultaneously, and results can be collected.

It’s not suitable for having 5 agents modify core architecture at the same time. For instance, if five agents all touch the same state management file, the same database schema, or the same API type definitions, conflicts are almost guaranteed. Even if git can merge them, the semantics may be broken.

A simple criterion: If two agents would modify the same file, don’t let them write code in parallel. Let them investigate in parallel, review in parallel, propose solutions in parallel, but when it comes to actually modifying files, partition them by directories, branches, or order.

Minimum Viable Structure: 1 Controller, 5 Workers

Beginners can start with a simple structure: the main session acts as controller, and 5 other agents act as workers. The controller divides tasks, sets boundaries, collects results, and makes final decisions; the workers only do their small tasks, without crossing boundaries.

The 5 agents can be divided like this:

The advantage: the first two agents help you understand the project; the third agent modifies code; the fourth agent verifies; the fifth agent documents the process. You don’t throw everyone into the code base blindly from the start.

Write a Plan First, Then Deploy Agents

Before running multiple agents in parallel, the most important step is to clearly define task boundaries. Creating agents comes later. First, have the main session output a Plan. It doesn’t need to be long, but must include these four things: what is the goal, which files might be touched, which files are prohibited from modification, and what each agent should deliver.

You can directly ask:

The key in this prompt is to first identify which tasks cannot run in parallel. Often, a valuable Plan will tell you that two of the tasks must be serial, and then tell you how to start the remaining agents.

Read-only Tasks Can Be Boldly Parallelized

The safest first step for parallelism is read-only. Let multiple agents simultaneously read code, trace call chains, review tests, find documentation, and analyze logs – this usually doesn’t mess with files. OpenAI Codex docs also mention that subagent workflows are well-suited for highly parallel tasks like codebase exploration.

For example, you can assign tasks like this:

After this step, you’ll have a project map. It’s much more stable than letting agents modify code directly. The main session hasn’t been polluted by massive search results, and each of the 5 agents compresses their findings into summaries.

To Modify Files, Use Worktrees for Isolation

Read-only tasks can run in parallel within one project directory. Writing code requires caution. The official Claude Code documentation specifically emphasizes worktrees: each parallel session runs in its own git checkout, files don’t touch each other. Git’s official docs also explain that a single repository can have multiple working trees, each checking out a different branch.

Beginners can think of worktrees as “multiple isolated copies of the same project.” They share git history, but file directories are separate. Agent A modifies login in project-agent-login, Agent B adds tests in project-agent-tests, and they don’t overwrite each other’s files directly.

A manual approach looks like this:

If you use Claude Code, there’s an easier way, like claude --worktree feature-auth from the official docs. You can learn the command later; first, understand the principle: Each agent that will modify files should work in its own isolated directory.

Give Every Agent a “File Boundary”

Worktrees isolate directories, but they can’t decide boundaries for you. You still need to tell each agent what it can and cannot modify.

The prompt for an implementation agent can be written like this:

This prompt sounds verbose, but it’s very useful. It fences the agent’s activity zone. When it encounters out-of-bounds requirements, it should stop and report, not expand its own permissions just to finish the task.

Don’t Let All 5 Agents Be Programmers

In practice, having all 5 agents write code isn’t stable. A better arrangement: 2 read-only analysts, 1 implementer, 1 tester, 1 for documentation and validation.

This arrangement has two benefits. First, fewer conflicts. The fewer agents actually writing code, the fewer file conflicts. Second, clearer validation. The tester and documentation agents didn’t participate in implementation, so they can more easily spot things the implementer missed.

If the project is large, you can have two implementation agents, but ensure they modify completely separate modules. For example, one only modifies frontend pages, the other only backend APIs; one only modifies docs, the other only tests. If the boundary is blurry, don’t parallelize writing.

Don’t Merge All at Once

After all 5 agents finish, never merge all changes into the main branch in one shot. The correct way is to review diffs one by one and run tests one by one.

You can follow this order: first, review the read-only agents’ reports to confirm the Plan is on track; then review the implementer’s diff to confirm no boundary violations; then review the tester’s results to confirm tests pass; finally, review documentation and handover notes to ensure continuity.

If using worktrees, check each worktree first:

Before merging, the main session should do a full review:

This step is critical. The time saved by multi-agent parallelism should not be lost during merging. First, review; then, merge; finally, run full tests.

Most Common Mistakes

First, treating parallelism as an acceleration button. Parallelism only suits tasks that can be split. If the task itself isn’t well thought out, throwing 5 agents at it will only amplify uncertainty.

Second, not setting file boundaries for agents. Agents easily modify global config, shared types, dependency versions to achieve their goals. One agent doing this is already dangerous; multiple agents doing it simultaneously becomes a nightmare.

Third, looking only at the final answer, ignoring process logs. Each agent should log which files it read, which files it modified, which commands it ran, which tests passed, and which points are still uncertain. Without handover records, you’ll have to ask everything again next time.

Fourth, ignoring cost. The Codex docs also warn that subagents consume more tokens because each agent makes its own model and tool calls. Parallelism has a cost. More tasks mean higher costs and easier rate limit hits.

A Beginner-Friendly Complete Flow

If it’s your first time, follow this flow. Don’t start with a large refactoring.

First, pick a medium-sized task, like “add email format validation to the login page and write tests.” Then have the main session only produce a Plan, not modify code. After the Plan is confirmed, launch 5 agents: A investigates the login flow, B checks existing form components, C implements changes in a worktree, D writes tests in another worktree, E writes handover notes and risk list.

After everything is done, the main session first aggregates, then reviews diffs of C and D. If C and D modified the same test file, the main session decides which changes to keep. Merge one, run related tests; merge the next, run tests again. Finally, run full test suite.

The entire flow seems like a few more steps than “just let the agent modify”, but it’s more suitable for real projects. In real projects, slow but stable is acceptable; the worst is after changes, no one knows what changed, why, or how to verify.

A Ready-to-Use Controller Prompt

Below is a prompt you can give directly to Claude Code or Codex. For the first time, only run the read-only Plan; after confirming it’s reliable, then release write permissions.

Final Reminder

The true value of multi-agent parallelism lies in separating exploration, implementation, testing, documentation, and validation – not just running many things on the screen simultaneously. The main session is responsible for judgment, worker agents for execution, worktrees for isolation, and tests for safety.

If you’re a beginner, remember just one sentence for the first time: Read in parallel first, then modify in isolation, finally merge one by one. Read-only parallelism helps you quickly understand the project; when writing code, always have file boundaries and worktrees; when merging, don’t take shortcuts – review diffs and run tests.

Used well, 5 agents can act like a small development team. Used poorly, 5 agents become 5 junior interns editing files simultaneously. The difference isn’t in how powerful the model is; it’s in whether you gave them clear boundaries and acceptance criteria.

Reference Links

• Claude Code: Run agents in parallel: https://code.claude.com/docs/en/agents
• Claude Code: Run parallel sessions with worktrees: https://code.claude.com/docs/en/worktrees
• Claude Code: Create custom subagents: https://code.claude.com/docs/en/sub-agents
• OpenAI Codex: Subagents: https://developers.openai.com/codex/subagents
• Google Developers Blog: Subagents have arrived in Gemini CLI: https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/
• Git: git-worktree Documentation: https://git-scm.com/docs/git-worktree

📚 Historical Articles

• Don’t treat Codex only as a code assistant; it’s becoming a workflow system
• Codex’s Pinned Threads: how to use them properly?
• Codex App beginner’s guide: just a few commands are enough
• AGENTS.md Complete Guide 2026: specifications, tools, examples
• Codex Best Practices: getting started guide and experience rules for better results
• Codex App Thread Scheduling Guide: current thread, new conversation, fork, worktree, subagents – which to choose?
• For complex requirements, don’t let AI write code first: multi-agent parallel Plan in practice
• Let Codex debug Codex: a post-mortem on mobile and desktop collaboration
• Keep Codex remotely connected when MacBook lid is closed
• The knowledge base doesn’t lack notes; it lacks a 500-character hot cache
• Codex’s “Annotations” feature: making AI modify code like editing a Word document
• Three-agent workflow in practice: after dual-agent battles, I added a referee
• From requirements to deployment: these 10 Codex App plugins let AI programming complete the entire project
• Agent memory is not RAG: the simplest way to give Codex and Claude long-term memory
• Advanced MacBook lid-closed connection: Codex mobile remote + Amphetamine + task handover
• Don’t waste agent session history: turn Claude Code and Codex histories into local knowledge bases
• Reproduce papers with Claude Code / Codex: can AI be a research assistant now?

If this article helped you, feel free to follow, bookmark, and share 👏🏻

Follow @thinkszyg for more real-world, production-level AI insights.