The short answer
To run multiple Claude Code agents at the same time:
- Split the work into tasks that touch different files.
- Start each agent in its own worktree with
claude --worktree <name>, one terminal per agent, so edits never collide. - Copy local config such as
.envinto each worktree with a.worktreeincludefile, and install dependencies there. - Monitor them from one screen with background agents:
claude --bg "<task>"starts one, andclaude agentslists them all. - Review and merge each branch on its own, then let Claude Code clean up the worktree.
Everything below works with Claude Code alone. The same pattern works for OpenAI Codex, or a mix of both.
Before you start
- Claude Code installed and signed in. Run
claude --versionto check. The flags below are in current releases; runclaude updateif one is missing. - A git repository with at least one commit. Worktrees branch from an existing commit.
- Usage headroom. Every agent spends from the same plan. Three agents use roughly three times the tokens of one, so check your limits first. AI coding agent costs breaks down what each plan includes.
Step 1: Pick tasks that can run side by side
Parallel agents go fastest when their work doesn't overlap. Before you start any agent, ask one question about each task: does it need another task's output, or edit the same files?
| Good to run in parallel | Better run in order |
|---|---|
| A new API endpoint and an unrelated settings page | A database migration and the code that reads the new column |
| Tests for module A and a refactor of module B | Two refactors of the same file |
| Docs updates and a bug fix | A shared type change and every feature that uses it |
When two tasks depend on each other, run the shared piece first (the interface, type or migration), then start the tasks that build on it. Three well-separated tasks beat six that keep meeting in the same files.
Step 2: Start each agent in its own worktree
A git worktree is a second checkout of your repository on its own branch, sharing the same history. Each agent edits its own copy of the files, so nothing it writes can land in another agent's work.
Claude Code creates worktrees for you. Open one terminal per agent in your repository root:
# Terminal 1
claude --worktree add-invoices-api
# Terminal 2
claude --worktree settings-page
# Terminal 3
claude -w fix-flaky-login-test
Each command creates .claude/worktrees/<name>/ on a new branch called worktree-<name>, then starts a Claude Code session inside it. Give each session its task as the first message.
Add the worktree folder to .gitignore once, so the checkouts don't show up as untracked files in your main checkout:
echo ".claude/worktrees/" >> .gitignore
Step 3: Give every worktree what it needs to run
A worktree is a fresh checkout of tracked files only. Your .env, local certificates and node_modules stay behind in the main checkout.
Create a .worktreeinclude file at the repository root. It uses .gitignore syntax, and Claude Code copies every matching gitignored file into each new worktree:
.env
.env.local
config/local-settings.json
Then ask each agent to install dependencies before it starts, or run your setup command yourself in the worktree directory. Watch for two shared resources:
- Ports. Two dev servers can't both listen on port 3000. Tell each agent which port to use.
- Databases. Agents running migrations against the same local database can interfere. Give each one its own database name, or run migrations in only one task.
Step 4: Watch every agent from one screen
Three terminal tabs work for three agents. Past that, use background agents. Each one is a full Claude Code session that keeps running without a terminal attached, and Claude Code moves it into its own worktree before it edits anything.
claude --bg "add pagination to the invoices API and cover it with tests"
claude --bg "fix the flaky login test in tests/auth"
claude agents
claude agents opens one view of every session, grouped by Needs input, Working and Completed. Press Space to peek at a session and answer its question without attaching, or Enter to open the full conversation. From scripts, claude attach <id>, claude logs <id> and claude stop <id> do the same jobs.
Step 5: Use subagents for parallel work inside one task
Subagents are different from parallel sessions. A subagent runs inside one Claude Code conversation, does a focused job in its own context window and reports back. They suit research and fan-out inside a single task: "use subagents to check every service for the old auth header."
When subagents edit files in parallel, give each one its own worktree. Ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter in .claude/agents/:
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor across every affected file, then run the tests and report the results.
Use parallel sessions for independent tasks you want to review as separate branches. Use subagents to split up one task.
Step 6: Review and merge one branch at a time
Every agent finishes on its own branch, so review is a normal branch review:
git worktree list
git log --oneline main..worktree-add-invoices-api
git diff main...worktree-add-invoices-api
Merge or open a pull request for each branch in turn, and run the tests after each merge. Merging one at a time means any conflict is small and easy to place. Before you merge, check three things in each branch: it does what the task asked, its tests pass, and it doesn't include changes outside its scope.
For larger batches, How to Review AI-Generated Code at Scale covers review queues and agent-as-reviewer workflows.
Step 7: Clean up
When you exit a worktree session, Claude Code checks for unsaved work. A clean worktree from an unnamed session is removed with its branch. A worktree with changes prompts you to keep or remove it. For worktrees you created yourself, or ones left behind by non-interactive runs:
git worktree remove .claude/worktrees/add-invoices-api
git worktree prune
How many agents should you run?
Start with two or three. The limit is rarely your laptop: Claude Code does its heavy work in the cloud, and each worktree costs about one copy of your source files on disk. The real limits are:
- Your review time. If finished branches start piling up, adding agents only grows the pile.
- Task independence. You need that many tasks that don't edit the same files.
- Your usage limits. Every agent draws from the same plan.
The right number keeps every agent busy and your review queue short.
How Chief runs multiple agents for you
Everything above works. Once you run several agents every day, most of your time goes to the steps around the code: choosing tasks that won't collide, writing each prompt, checking which agent is waiting, and reviewing what came back. Chief takes over that loop.
- You set the goal, Chief plans the work. Describe the outcome in a sentence. Chief breaks it into milestones, each with a definition of done and the milestones it depends on.
- Parallel by plan. Chief runs every milestone whose dependencies are done at the same time. It plans shared pieces such as types, interfaces and migrations first, and it chains or merges milestones that would mostly edit the same files, so parallel agents stay out of each other's way.
- Runs on your computer, with your subscriptions. The Chief relay starts Claude Code, Codex and other agents in your project folder, using the accounts you already pay for. Each agent commits only its own files, tagged with its task, so every change traces back to its milestone.
- Every result is reviewed. Chief checks each finished milestone against its definition of done. Decisions only you can make go into one queue.
- Auto mode with a budget. Set a task limit and a weekly cap on your provider's usage, and Chief keeps working towards your goals until it reaches either one.
- Check in from anywhere. Approve milestones and answer the queue from your phone, from the Chief MCP server in Claude, Claude Code or Codex, or from a DM with Chief for Discord.
You set the direction and make the calls. Chief keeps the agents working. See Chief and Claude Code for how the two fit together, and the multi-agent orchestration guide for the bigger picture.
FAQ
Can I run multiple Claude Code sessions in the same folder?
Yes, but agents in the same folder edit the same files, so one agent's changes can land in the middle of another's work. Give each session its own worktree with claude --worktree <name>, or plan the tasks so they never touch the same files, which is how Chief runs parallel agents in one project folder.
What is the difference between subagents and parallel agents?
A subagent runs inside one Claude Code conversation and reports its findings back to that conversation. A parallel agent is a separate Claude Code session with its own task and, usually, its own branch. Use subagents to split up one task and parallel sessions for independent tasks.
Do parallel Claude Code agents share my usage limit?
Yes. Every session signed in to the same account draws from the same plan, so three agents use your limit about three times as fast as one. AI coding agent costs compares plans and limits.
Can I run Claude Code and Codex in parallel on the same repository?
Yes. Start each tool in its own worktree with git worktree add, then run claude in one and codex in the other. Chief runs both from one plan and sends each milestone to the agent you choose. See the multi-provider orchestration guide.
Is there a Claude Code orchestrator?
Claude Code includes subagents, background agents and the claude agents view for running several sessions yourself. An orchestrator such as Chief adds the planning, dispatch, review and queue around those sessions, so the agents keep working towards your goals without you starting each one.