GuideAugust 31, 2026

How to Run Multiple Claude Code Agents in Parallel

One task per worktree, one review path per result, and no shared checkout to corrupt.

The safest way to run multiple Claude Code agents in parallel is to give every independent task its own Git worktree. Claude Code can create those worktrees itself. Agentastic adds the operating layer around them: repository setup, a status view, native terminals, container isolation, browser verification, diff review, and a clean path to a pull request.

Parallel Claude Code worktrees branching from one Git repository with isolated environments and ports

This guide shows both workflows so you can choose the smallest tool that solves your problem.

The short version#

What you needBest starting point
Two isolated Claude sessions and no additional UIclaude --worktree <name>
Full control over branches and directoriesManual git worktree add plus one terminal per task
Several agents, repeatable setup, review, browser testing, or mixed providersAgentastic workspaces
Stronger runtime isolation for databases or system packagesAgentastic container mode

Anthropic's official worktree guide documents the --worktree flag, .worktreeinclude, cleanup, and subagent isolation. Its broader parallel agents guide explains when to use worktrees, subagents, agent view, or coordinated agent teams.

Why separate terminals are not enough#

Two terminal windows pointed at the same repository still share one working directory. The sessions can overwrite the same uncommitted file, invalidate each other's build output, compete for the Git index, and start services on the same port.

A branch does not fix that by itself. A branch is a Git reference; a worktree is a separate directory. With one worktree per task, each Claude session has its own files, untracked state, dependencies, build artifacts, and diff.

That changes the failure mode. Two agents may still produce changes that conflict when you merge them, but they cannot silently corrupt the same live checkout while they work.

Option 1: use Claude Code's native worktrees#

From a Git repository, start one session per task:

bash
claude --worktree fix-checkout-total claude --worktree add-coupon-tests claude --worktree document-refund-api

Claude creates an isolated checkout for each session. If the worktree needs ignored local files such as .env.local, add the paths to .worktreeinclude:

text
.env .env.local config/secrets.json

Use this path when Claude Code is the only agent you need and you are comfortable handling repository setup, processes, review, and cleanup through Claude's own surfaces and Git.

Option 2: create the worktrees manually#

Manual Git worktrees remain the most portable approach:

bash
git fetch origin git worktree add -b agent/fix-checkout \ ../store-fix-checkout origin/main git worktree add -b agent/coupon-tests \ ../store-coupon-tests origin/main

Then start Claude in each directory:

bash
cd ../store-fix-checkout && claude cd ../store-coupon-tests && claude

This gives you complete control and no extra application. It also makes you responsible for naming, dependency installation, ignored files, server ports, attention signals, diff review, merging, and removal.

Option 3: run parallel Claude Code workspaces in Agentastic#

Agentastic uses the provider CLI you already installed and authenticated. It does not replace Claude Code or proxy its model calls.

1. Verify Claude Code first#

bash
which claude claude --version

If it does not launch in a normal terminal, fix that before debugging another layer. See Agentastic installation for the current install flow.

2. Open the repository once#

Open the project in Agentastic and choose Agent Home. Select the repository, the base branch, Claude Code, and Worktree mode.

Keep each task bounded. A useful prompt names the outcome, constraints, and verification command:

text
Fix the checkout rounding regression. Do not change the public money API. Preserve the existing USD and EUR behavior. Run the focused checkout test suite and explain the root cause when finished.

3. Launch one workspace per independent task#

Create separate tasks for work that can land independently:

  • fix-checkout-rounding
  • add-zero-coupon-tests
  • update-refund-docs

Agentastic creates a worktree and branch for each task, runs the repository setup script, starts Claude Code in a native terminal or Chat transcript, and keeps the session attached to that workspace.

You can also select multiple instances in Agent Home when you intentionally want several attempts. For unrelated work, separate prompts are usually easier to review than sending one large prompt to every agent.

4. Prepare every worktree automatically#

Put repeatable setup in .agentastic/setup.sh:

bash
#!/usr/bin/env bash set -euo pipefail if [ -f "$AGENTASTIC_MAIN_REPO_PATH/.env" ] && [ ! -f .env ]; then cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .env fi if [ -f package-lock.json ]; then npm ci elif [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile fi echo "Ready: $AGENTASTIC_BRANCH"

Make it executable:

bash
chmod +x .agentastic/setup.sh

The script runs from the new checkout and receives the branch, repository, worktree path, base branch, and commit as environment variables. Keep it idempotent so you can safely rerun it. The complete contract is in Setup & Teardown Scripts.

5. Monitor attention, not terminal noise#

The Agents navigator shows which sessions are running, waiting for input, finished, failed, or ready for review. Agentastic routes supported Claude lifecycle events into its attention system, so an approval request does not disappear in a background terminal.

Use Shift-Command-U to jump to the next agent that needs attention. See Notifications for the event model.

6. Verify each workspace independently#

An agent saying "done" is not evidence. For each result:

  1. Read the test output.
  2. Inspect every changed file in the built-in diff.
  3. Run the focused test yourself when the change matters.
  4. Start the worktree's development server.
  5. Use the built-in browser or dev browser commands to verify UI behavior.
  6. Run a fresh Claude, Codex, CodeRabbit, or Greptile review when appropriate.

Agentastic's code-review workflow can launch multiple independent reviewers against the same captured diff.

7. Merge one result at a time#

Push the branch and open a normal pull request:

bash
git push -u origin fix-checkout-rounding gh pr create --fill

Reviewing and merging sequentially is usually safer than merging three related branches at once. Rebase or update remaining worktrees after an upstream merge changes their assumptions.

What should run in parallel?#

Good parallel tasks have small overlap:

  • Tests for separate modules.
  • A bug fix and unrelated documentation.
  • Independent endpoints.
  • Several solution attempts where you intend to keep only one.
  • Research, implementation, and review when only one agent edits the final branch.

Keep these sequential:

  • Two refactors of the same central type.
  • A schema migration and code that depends on its final shape.
  • Several agents editing the same generated file.
  • Work that needs a shared, mutable development database.

The practical limit is your review capacity. If completed diffs accumulate faster than you can validate them, adding more agents decreases throughput.

When to use containers instead of worktrees#

Worktrees isolate repository files. They do not isolate host processes, credentials, package caches, ports, or external services. Use Agentastic's container mode when a task changes system packages, runs untrusted tooling, needs its own services, or should have a tighter network and mount policy.

Start with one clean loop#

Run one bounded Claude task through create, setup, execute, verify, review, merge, and cleanup. Then add a second independent task. Parallelism is useful only after each individual workspace is reproducible.

Download Agentastic for macOS or follow Your First Agent for the complete first-run path.

Sources and further reading#