Guides

How to run several Claude Code agents in parallel

One coding agent works through a task step by step. Several agents can work on separate parts of a project at the same time, as long as each one has its own place to work and you have a plan for bringing the work back together. This guide covers the plain git setup, what tends to go wrong, and how Yami does the same steps for you.

Why one folder is not enough

Two agents in the same checkout share one working tree: the same files on disk, the same staging area and the same checked out branch. When one agent edits a file the other is reading, the second sees changes it did not make and may "fix" or undo them. A test run by one picks up the other's half finished edits. A git add -A from one sweeps up the other's work into its commit. Nothing locks the files, so this is quiet and hard to trace.

The answer is to give each agent its own checkout. Separate clones work, but each carries a full copy of the history and must be synced by hand. Git worktrees are the lighter way.

Step 1: one worktree and one branch per agent

A worktree is an extra working folder attached to the same repository. All worktrees share one history and one set of branches, but each has its own files and its own checked out branch. From your main checkout:

git worktree add -b agent/login ../myapp-login main
git worktree add -b agent/search ../myapp-search main
git worktree list

Each add creates a new branch from main and checks it out in a new folder next to your project. Git refuses to check out one branch in two worktrees at once, which is the guarantee you want: no two agents on the same branch. Then start one agent in each folder, each in its own terminal:

cd ../myapp-login && claude
cd ../myapp-search && claude

Recent versions of Claude Code also have a --worktree option that creates a worktree for a session; claude --help shows whether yours has it. The git worktrees guide covers the commands in more detail.

A new worktree holds only tracked files, so .env and node_modules are missing. Copy or install them in each worktree before an agent runs the tests.

Step 2: split the work so the branches rarely meet

Worktrees keep agents apart while they work. They do not prevent conflicts at merge time: if two agents change the same lines, git still asks you to choose. The task split is your main defence.

• Give each agent a part with clear edges: a feature, a module, a page or a set of tests.
• Name what each agent owns in its prompt (files or folders), and ask it to leave the rest alone.
• Keep shared files with one agent, such as package manifests, lockfiles, route tables and config, or change them yourself before the agents start.
• Keep tasks small: a branch that lives for days drifts away from main.
• Write the plan down first: what each agent does, the order the branches merge in, and what done means (the tests pass, the build works).

Step 3: review and merge one branch at a time

When an agent says it is done, look at what it changed since it started:

git log --oneline main..agent/login
git diff main...agent/login

The three dot form shows only the agent's changes, not what happened on main in the meantime. With git 2.38 or newer you can try a merge without touching your files. This command exits with status 1 and lists the conflicting files if the merge would conflict:

git merge-tree --write-tree --name-only main agent/search

Then merge into your branch, run the tests, and only then move on to the next branch:

git switch main
git merge --no-ff agent/login

--no-ff always makes a merge commit, so the agent's work stays grouped, and git revert -m 1 <merge-commit> takes it back out if needed. Follow the order in your plan: if the search work builds on the login work, merge login first, then rebase the search branch on the new main or let its agent catch up.

Step 4: clean up

git worktree remove ../myapp-login
git branch -d agent/login
git worktree prune

git worktree remove refuses while the worktree has uncommitted changes, and git branch -d refuses while the branch is not merged, so unkept work is safe. prune tidies up after folders deleted by hand.

The limits of a personal plan

Every agent you start draws from the same account. On a Claude subscription the usage limits are shared by all your sessions, so four agents use up the allowance about four times as fast as one doing the same work, and when the limit is reached they all stop. Read your plan's terms as well: personal subscriptions are made for one person at the keyboard, and many parallel or scheduled runs may not be what they allow. For bigger runs, an API key billed per token is made for that kind of use. More agents also means more to review: three or four branches at a time is already a lot to read with care.

How Yami does it: ventures

Yami is a free desktop app for macOS (Apple silicon) and Windows 11 that does these steps for you in what it calls a venture. You describe the goal, and a leader agent writes a plan in phases and tasks that you can read. Agents then take the tasks, up to eight at once (four by default; you change it in Settings).

Each agent works in its own git worktree under ~/Yami/Worktrees, on its own branch, so no two agents touch the same checkout. When the leader says a branch is good, Yami merges it into the branch you are on, with your repository's git hooks turned off for that merge. Your approval mode decides what asks first:

• Manual, Accept edits and Plan: a card before each agent starts and before each merge.
• Auto: agents start on their own with a notice; merges still ask.
• Bypass: nothing asks; each start and merge is logged and shown, with Stop and Undo merge.

A folder without git gets one agent at a time. You can set a token budget for a venture, and at the limit no new agent starts until you raise it. Agents run on the engine you choose: Claude Code or Codex on your own plan, Yami's built-in engine, an API key or a local model. When they run on a personal plan, the venture page shows a short note about the plan's terms.

Claude and Claude Code are trademarks of Anthropic, PBC. Yami works with Claude Code but is independent: it is not made by, affiliated with or endorsed by Anthropic.