How to run multiple Claude Code agents at once

To run several Claude Code agents at once, start each one in its own git worktree with claude --worktree <name> in a separate terminal, or hand tasks to background sessions with claude --bg and watch them in agent view (claude agents); in a git repository, each of those sessions moves into its own worktree before it edits anything. The worktree keeps parallel agents from editing each other's files: every agent gets its own files and branch. What remains to manage is usage, which every agent draws on, and merging and reviewing what they produce.

Agents in one checkout overwrite each other

Nothing stops you opening two terminals in the same repository and running claude in both. The trouble is that both sessions then edit the same files on the same branch. One agent's edit lands under the other's tests, one reformats a file the other is halfway through changing, and neither one knows. The Claude Code documentation on running agents in parallel names the fix: when tasks touch the same files, isolate them with worktrees.

A git worktree is a second working directory attached to the same repository. It has its own files and its own branch but shares the repository's history and remote, so the agent's commits land in the same repository as yours.

Start each session in its own worktree

Claude Code creates the worktree for you. Run this in one terminal:

claude --worktree feature-auth

and this in another:

claude --worktree fix-flaky-test

Each command creates a checkout under .claude/worktrees/<name>/ on a new branch called worktree-<name> and starts the session inside it. -w is the short form, and leaving out the name makes Claude generate one. Add .claude/worktrees/ to your .gitignore so the worktrees do not show up as untracked files in your main checkout.

If you would rather put worktrees beside the repository or start from an existing branch, create them with git and run claude inside. The first command creates a new branch, the second checks out one that already exists:

git worktree add ../shop-feature-a -b feature-a
git worktree add ../shop-bugfix fix-issue-456
cd ../shop-feature-a && claude

Git will not check out one branch in two worktrees unless you force it, so every agent needs its own branch, and each agent's work arrives as a branch you can diff and merge on its own.

A new worktree needs its own setup

A worktree is a fresh checkout of tracked files only. Dependencies are not installed and gitignored files such as .env are missing, so the first thing an agent does in a new worktree should be your project's install step. To copy gitignored files automatically, add a .worktreeinclude file to the project root. It uses .gitignore syntax, and only files that match a pattern and are gitignored are copied:

.env
.env.local
config/secrets.json

This applies to every worktree Claude Code creates with git, including subagent worktrees and the desktop app's. If agents start dev servers, give each worktree a different port; they are separate directories on the same machine.

Choose what new worktrees branch from

New worktrees branch from the repository's default branch, usually main, so they start clean and ignore your unpushed commits. When agents need to build on work in progress, set worktree.baseRef to "head" in your settings so worktrees branch from your current local HEAD instead:

{
  "worktree": {
    "baseRef": "head"
  }
}

The setting takes only "fresh" (the default) or "head", not a branch name. To start from a specific existing branch, use the second git worktree add form above.

Cleaning up after a worktree session

When you exit an interactive worktree session, Claude Code removes a clean worktree from an unnamed session automatically, asks first for a named one, and asks whether to keep or remove a worktree that holds changes or new commits. Removing deletes the directory and its branch with everything in them. Sessions run with -p are not cleaned up, so remove those yourself with git worktree remove; if git refuses because the worktree is locked, run git worktree unlock on it first. git worktree list shows what is still on disk.

Bash command approvals are shared: choosing "Yes, and don't ask again" for a command in a worktree session saves the rule to the main checkout's .claude/settings.local.json, so it applies in the repository's other worktrees too. On Windows the rule stays with that worktree.

Background sessions and agent view track the agents for you

Separate terminals work, but you have to check each one to learn which agent is waiting. Agent view replaces that with one list. Start tasks as background sessions from your shell:

claude --bg --name auth "add rate limiting to the login endpoint"
claude --bg --name flaky "find out why SettingsChangeDetector fails intermittently"
claude agents

Each --bg session keeps running without a terminal attached and prints its short ID with the commands to manage it: claude attach, claude logs and claude stop. claude agents opens the list, where each row shows the session's state: working, needs input, idle, completed, failed or stopped. You can also type a task at the bottom of agent view and press Enter to dispatch another session.

Select a row and press Space to peek: you see the question it is waiting on or its result, and you can reply without leaving the list. Press Enter or → to attach to the full conversation and ← on an empty prompt to go back. A permission prompt cannot be answered from the peek panel; attach to answer it. To move a session you already have open into the list, run /bg in it.

Isolation is automatic here unless you turn it off with the worktree.bgIsolation setting. In a git repository, a session dispatched from agent view or started with --bg moves into its own worktree under .claude/worktrees/ before it edits any file. When it has changed code, it commits without asking and pushes the branch if the repository has a remote, and it never pushes to main or master. If you want to handle git yourself, say so in the task or in CLAUDE.md. A session you moved to the background with /bg is the exception: it keeps editing wherever it already was.

Subagents and agent teams split one task inside a session

Worktrees and background sessions run independent tasks that you assign. Claude Code also has two ways for one session to fan out on its own:

• Subagents are workers a session starts for a side task. Each has its own context and returns a summary, which keeps search results and logs out of your main conversation. They share the session's working directory unless you ask Claude to "use worktrees for your agents" or put isolation: worktree in a custom subagent's frontmatter. The /batch skill packages this: it splits one large change into 5 to 30 worktree-isolated subagents.
• Agent teams are a lead session that coordinates several full Claude Code sessions and the teammates message each other directly. They are experimental and off until you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment or in the env block of settings.json. Teammates are not isolated in worktrees, so split the work so that each teammate owns different files. While teams are on, a subagent Claude names can launch as a teammate instead, and then its isolation setting does not give it a worktree.

The Claude desktop app offers the first approach in a window: + New session (Cmd+N on macOS) starts another session, and the worktree option next to the branch name gives it its own checkout.

Every agent draws on the same usage

Running agents in parallel does not create more capacity. On a subscription, all your sessions draw on the same plan limits, and the agent view documentation gives the scale: ten agents in parallel use quota roughly ten times as fast as one. Subagents send their own requests on top of the main conversation's. For agent teams, the costs page estimates about seven times the tokens of a standard session when teammates run in plan mode. Run /usage to see your plan limits and when they reset before you start ten of anything.

Review is the real limit

Every agent's work ends as a branch someone has to read and merge. Parallel work pays off when the tasks are independent and small enough to review one at a time: a bug fix, a test investigation and a dependency upgrade, not three slices of the same feature that will conflict at merge. Give each agent a task with a clear definition of done, ask it to run the tests before reporting back, and merge one branch before you start reviewing the next. Start as many agents as you can review, not as many as you can launch.

How Armadai handles parallel agents

Armadai is a native macOS app that puts each project folder in its own workspace on one infinite canvas, and you can run several agents in each workspace, Claude Code and Codex side by side. It adds two things to the methods above.

The first is task hand-off. You write a task on a workspace's board, choose Run with Claude or Run with Codex, and Armadai starts an agent if needed, gives the run its own Git worktree and tracks it through to review. Successful work comes back as a draft pull request for you to approve or send back. An optional setting lets available agents pick up Ready tasks, with limits on simultaneous runs and checks for overlapping work.

The second is the session sidebar, which shows every session across your projects as working, idle or needing approval. You can review a waiting agent's request and approve it from the sidebar without leaving the workspace you are in, although some prompts have to be answered in the session itself.

Armadai runs the Claude Code and Codex you already have, under your own accounts, so the usage limits above still apply; the Armadai plan does not limit workspaces or agents. It is a paid app with no free plan: $20 a month or $120 a year after a 7-day free trial that requires a payment method. If claude --worktree in a few terminals or agent view covers your work, you do not need it.