Parallel agents on macOS

Git worktrees for Claude Code, Codex, and any coding agent.

Two agents in one folder overwrite each other. A worktree fixes that in one command — and then leaves you to rebuild the environment around it. This page covers what worktrees do for agents, what Claude Code and Codex now do natively, and the three levels of isolation you can choose between.

Download for macOS
Developer ID signed · Notarized by AppleSafety, checksums & removal
Jump to the comparison

Level 1

A linked worktree

Another checkout of the same repository. Isolates files. Carries nothing else.

Level 2

A managed worktree

The same checkout, created and torn down for you, with the agent already running in it.

Level 3

A standalone copy

The project as it exists on disk right now — local files, dependencies, uncommitted work — with its own Git repository.

The short answer

How do you run multiple AI coding agents on one repository?

Give every agent its own directory. A Git worktree is the cheapest way to do it: a second working directory on its own branch, backed by the same repository history.

One worktree per agent
git worktree add ../app-auth -b auth
cd ../app-auth
claude

Claude Code and the Codex app now do this for you — claude --worktree creates, enters, and cleans up a worktree per session. The part nobody automates for you is everything the checkout does not contain: your .env, your installed dependencies, your uncommitted work, and the ports and databases all the agents still share.

That gap is why a second primitive exists. lpm creates worktrees too, and lpm Duplicate can instead copy the project exactly as it sits on your disk into a standalone project with its own Git repository — then start the agent in each one.

Before you fan out

Five things a Git worktree does not carry

Creating the worktree is one command. These are the five reasons the agent inside it still cannot run your project.

  1. 1

    Your .env and other ignored files are gone

    What you see
    The agent starts, the app boots, and every environment variable is undefined.
    Why
    git worktree add checks out tracked files only. Anything in .gitignore — .env, .env.local, local certificates, editor settings — was never in the commit, so it is never in the worktree.
    What fixes it
    Claude Code reads a .worktreeinclude file and copies gitignored files that match it. That applies to worktrees Claude creates. For everything else you copy them yourself, or start from a copy of the project instead of a checkout.
  2. 2

    node_modules is empty in every new worktree

    What you see
    Ten minutes of install per agent, and a few hundred megabytes each, before any work starts.
    Why
    Dependencies are ignored files too. A fresh checkout has none of them, and symlinking one shared directory breaks resolution in tools that walk the real path.
    What fixes it
    Install per worktree and accept the cost, or duplicate the project so the already-installed dependencies come with it.
  3. 3

    The work in progress on your desk does not come along

    What you see
    You ask an agent to continue what you were doing, and it starts from a commit you moved past hours ago.
    Why
    A worktree branches from a commit. Claude Code branches from your default branch by default, or from local HEAD when worktree.baseRef is set to head. Neither reproduces uncommitted edits or untracked files.
    What fixes it
    Commit or stash first, or copy the working project rather than checking one out.
  4. 4

    Two agents cannot try the same branch

    What you see
    fatal: 'main' is already checked out at '/path/to/repo'
    Why
    Linked worktrees share one repository, and Git refuses to check out a branch in two of them — a commit in one would leave the other pointing at a stale state of the same branch.
    What fixes it
    Give each agent its own branch, or give each one an independent repository so the restriction no longer applies.
  5. 5

    Ports, databases, and Docker volumes are still shared

    What you see
    The second dev server cannot bind. Two agents run migrations against one database and corrupt each other's fixtures.
    Why
    Every isolation model on this page draws its boundary at the filesystem. Nothing about a separate directory reserves a port, namespaces a Postgres schema, or forks a Docker volume.
    Where this stands
    No worktree model solves this, and lpm does not solve it yet either. What lpm does today is catch it: it checks declared ports before a project starts, tells you which process is holding one, and can free it or stop the start. Giving every copy its own ports is what we are building next. Until it lands, real runtime isolation means per-copy configuration, separate services, or containers.
What the agents already do

Claude Code and Codex create worktrees for you

Before adding a tool, check what your agent ships with. For a single session on a clean branch, the built-in flag is usually enough.

Claude Code

Built in

Pass --worktree (or -w) with a name and Claude creates the worktree, starts the session inside it, and offers to remove it on exit. Worktrees land under .claude/worktrees/<name>/ on a branch named worktree-<name>. Subagents can get the same treatment with isolation: worktree in their frontmatter.

claude --worktree feature-auth

# copy gitignored files into every new worktree
cat .worktreeinclude
.env
.env.local

New worktrees branch from your default branch unless you set worktree.baseRef to head. Anthropic's own documentation is explicit that a worktree is a fresh checkout and you still have to initialize the environment inside it. Claude Code worktree documentation

Codex

Built in

The Codex app runs agents in parallel threads, each on its own worktree. Starting a thread on a worktree creates a directory under $CODEX_HOME/worktrees/ and checks out the target branch there, leaving your main checkout untouched.

Same boundary as everything else: the checkout is isolated, the environment around it is not. Codex documentation

GitHub Copilot, Gemini CLI, OpenCode, and the rest

Bring your own

Worktrees are a Git feature, not an agent feature, so any terminal agent works inside one. What varies is whether the agent creates and cleans up the directory for you, or whether you script it.

git worktree add ../app-copilot -b copilot-task
cd ../app-copilot
cp ../app/.env .env
pnpm install
copilot

This is the loop that agent-specific flags remove — and the loop that stays if the agent you use does not have one.

Five ways to isolate an agent

Git worktree vs lpm Worktree vs lpm Duplicate

The same table with the two built-in agent flags alongside them, so you can see exactly where each boundary is drawn.

Isolated working directory

All five
Yes

Git repository

git worktree
shared
claude --worktree
shared
Codex worktrees
shared
lpm Worktree
shared
lpm Duplicate
independent

Created and removed for you

git worktree
No
claude --worktree
Yes
Codex worktrees
Yes
lpm Worktree
Yes
lpm Duplicate
Yes

Carries .env and other ignored files

git worktree
No
claude --worktree
.worktreeinclude
Codex worktrees
No
lpm Worktree
No
lpm Duplicate
Yes

Carries installed dependencies

git worktree
No
claude --worktree
No
Codex worktrees
No
lpm Worktree
reinstall
lpm Duplicate
Yes

Starts from your uncommitted work

git worktree
No
claude --worktree
No
Codex worktrees
No
lpm Worktree
No
lpm Duplicate
Yes

Two agents on the same branch

git worktree
No
claude --worktree
No
Codex worktrees
No
lpm Worktree
No
lpm Duplicate
Yes

Create many at once

git worktree
No
claude --worktree
No
Codex worktrees
one per thread
lpm Worktree
1–50
lpm Duplicate
1–50

Queue the same prompt on each

git worktree
No
claude --worktree
No
Codex worktrees
No
lpm Worktree
Yes
lpm Duplicate
Yes

Inherits the project's services and actions

git worktree
No
claude --worktree
No
Codex worktrees
No
lpm Worktree
Yes
lpm Duplicate
Yes

Works with any terminal agent

git worktree
No
claude --worktree
Claude only
Codex worktrees
Codex only
lpm Worktree
Yes
lpm Duplicate
Yes

Isolates ports, databases, Docker volumes

All five
No

The last one is worth reading twice. Nothing above reserves a port, namespaces a database, or forks a Docker volume — including both lpm entries. Filesystem isolation is where all five stop, and it is the collision developers running parallel agents hit most often. lpm already catches the port half of it at start time and tells you which process is holding the port; assigning each copy its own is what we are building next, and this line will change when it ships.

One prompt, three agents

Both primitives, the same fan-out

lpm does not ask you to give up worktrees. The same dialog creates either kind, queues the work, and cleans up after it.

lpm Worktree

Linked worktrees, created in a batch

Each one is a real Git worktree on its own branch, sharing the repository. Ignored files are not carried over, the same as raw Git — tick the reinstall option when the copy needs its dependencies.

  • Real linked worktrees, removed with their branch when you delete them
  • Lightest option when the checkout is all the agent needs

lpm Duplicate

Standalone copies of the project you have now

An APFS copy-on-write clone with its own Git repository, carrying uncommitted work, ignored files, and installed dependencies. Regenerable build caches are left behind.

  • Optionally strip uncommitted changes, pull the latest commit, or reinstall dependencies
  • Each copy is independent, so several can sit on the same branch
  1. 01

    Open Duplicate, choose worktrees or standalone copies, and set how many — up to 50.

  2. 02

    Label them, group them in the sidebar, and pick the action or command each one should run, with the prompt to send.

  3. 03

    Watch every copy's agent status from the sidebar, review the diffs, and remove the copies you do not keep.

The agents can drive this themselves. lpm installs skills for Claude Code and Codex, so an agent asked to try three approaches can create its own copies, run the work in them, wait for the others to settle, and clean them up when you have merged the one you want.

See it in action

Projects, terminals, agents, a built-in browser — one click each

Watch lpm boot a project's services and hand it straight to Claude Code. The demo below is a recording — lpm is a macOS app, so the clickable version runs on desktop.

lpm is a macOS app with a multi-pane terminal workspace. Open this page on your computer to try the interactive demo.

Get lpm for Mac
Pick one

Which isolation model do you actually need?

Work down the list and stop at the first line that describes your repository.

  • One agent, one clean branch, and setup is cheap

    Your agent's built-in flag

    claude --worktree or a Codex thread. Nothing to install, and cleanup is handled on exit.

  • Several agents, and your repository needs no local setup

    Git worktree, or lpm Worktree for the batch

    The checkout is all the agent needs, so the lightest primitive wins. Use lpm Worktree when you want several at once with a prompt queued on each.

  • The agent needs your .env, your dependencies, or your uncommitted work

    lpm Duplicate

    A checkout cannot reproduce state that was never committed. A copy of the working project can.

  • Several agents should attempt the same branch and you keep the best

    lpm Duplicate

    Linked worktrees refuse a branch that is already checked out. Independent repositories have no such restriction.

  • You are running agents with approvals turned off

    A container or a VM

    None of these models is a security boundary. A separate directory does not contain a command that decides to touch the rest of your machine.

FAQ

Git worktrees and AI agents, answered

  • Does Claude Code support Git worktrees?

    Yes. Pass --worktree or -w with a name and Claude Code creates the worktree, starts the session in it, and offers to remove it when you exit. Worktrees are created under .claude/worktrees/<name>/ on a branch named worktree-<name>, and subagents can be pinned to their own worktree with isolation: worktree in their frontmatter.

  • Does a Git worktree copy files like .env or node_modules?

    No. git worktree add checks out tracked files from the commit you point it at. Anything ignored by Git — .env files, node_modules, virtualenvs, local certificates — is absent from a new worktree. Claude Code can copy selected ignored files into the worktrees it creates if you add a .worktreeinclude file, and lpm Duplicate carries them because it copies the project folder instead of checking one out.

  • How do I run multiple Claude Code sessions at once?

    Give each session its own directory so the agents cannot overwrite each other's edits, then start Claude in each one. That directory can be a Git worktree, a standalone copy of the project, or a container. Running several sessions costs nothing extra on your plan; the practical limit is how many diffs you can review.

  • Can two Git worktrees check out the same branch?

    No. Git refuses with 'fatal: <branch> is already checked out at <path>', because a commit in one worktree would leave the other pointing at a stale state of the same branch. If you want several agents to attempt the same branch and then keep the best result, each one needs an independent repository rather than a linked worktree.

  • Does Codex support parallel agents and worktrees?

    Yes. The Codex app runs agents in parallel threads and can back a thread with a Git worktree, created under $CODEX_HOME/worktrees/ so your main checkout stays untouched. As with Claude Code, the isolation covers the checkout, not the environment around it.

  • Do Git worktrees isolate ports, databases, or Docker volumes?

    No, and lpm does not isolate them yet either. Every model on this page draws its boundary at the filesystem, so two agents in two worktrees will still fight over port 3000 and still run migrations against the same database. lpm checks declared ports before a project starts and tells you which process is holding one, so the collision surfaces immediately instead of halfway through a run, and per-copy port assignment is what we are building next. Until then, isolating runtime state needs per-copy configuration, separate services, or containers.

  • Can I use Git worktrees with GitHub Copilot, Gemini CLI, or OpenCode?

    Yes. Worktrees are a Git feature, so any terminal agent runs inside one. What differs is whether the agent creates and cleans up the directory for you. Claude Code and Codex do; for the others you run git worktree add yourself, or use a tool that does the batch for you.

  • Is there a Git worktree MCP server or agent skill?

    lpm installs skills for Claude Code and Codex that teach the agent how to drive lpm directly. An agent can then create its own isolated worktrees or copies, run work in them, wait for the others to settle, and remove them — without you translating each step yourself.

  • What is the difference between lpm Worktree and lpm Duplicate?

    lpm Worktree creates real linked Git worktrees on their own branch, sharing your repository. lpm Duplicate creates a standalone folder with its own Git repository, starting from the project exactly as it is on disk. Both create up to 50 at a time, inherit the project's services and actions, and can queue an agent action with a prompt on each one.

  • Does lpm Worktree copy my .env file and dependencies?

    No. lpm Worktree creates a real Git worktree, so it has the same blind spot as raw Git: ignored files are not carried over. There is an option to reinstall dependencies in each worktree. If the copy needs your local files and current state, use lpm Duplicate instead.

  • How much disk does each copy use?

    A linked worktree is very compact because the repository data is shared. lpm Duplicate starts with an APFS copy-on-write clone, so unchanged file data is shared by the filesystem at first and storage grows as the copies diverge. Regenerable build caches such as .next, dist, and target are skipped rather than cloned.

  • How many parallel agents should I run?

    Fewer than you can create. Spinning up five agents takes one command; reviewing five diffs and landing five branches does not scale the same way. Most developers settle around three to five concurrent sessions, and the bottleneck is review, not isolation.

Keep reading

Git worktree alternative

The standalone-copy side of the comparison in full: what Duplicate carries that a checkout cannot.

Best terminal for Claude Code & Codex

Run AI coding agents side by side with each project’s services, logs, and status in view.

Connect AI agents to your dev environment

Give agents a CLI to run services, read logs, wait for readiness, and fan out into project copies.

Review agent changes in the terminal

Inspect every changed file and diff before you merge the result of a parallel agent run.

Worktrees when a checkout is enough. Copies when it is not.

Download lpm for macOS and fan one prompt out to Claude Code, Codex, or any terminal agent — in linked worktrees or standalone project copies, whichever the task needs.

Download for macOS
Developer ID signed · Notarized by AppleSafety, checksums & removal
View the open-source project