Download

How to Run Multiple Claude Code Sessions in Parallel (Worktrees, Codex Too)

Updated 2026-10-15 · by Murilo Prataviera, maker of Aki

One agent is fast. Three agents on three features at once is where the time really goes away, as long as they don't step on each other. Run two sessions in the same folder and they edit the same files, fight over the same branch and break each other's builds. The fix is to give every session its own working copy. Below is how to do that with Claude Code's built-in worktrees, with plain git, and with Codex, plus the parts that usually go wrong: ports, .env files, and knowing which session is waiting on you.

Quick answer

  • One session per worktree. claude --worktree feature-auth (or claude -w feature-auth) creates .claude/worktrees/feature-auth/ on a new branch and starts Claude there.

  • Plain git works too: git worktree add ../app-feature-a -b feature-a, then run claude inside that folder.

  • Codex: codex --worktree starts a session in a new managed worktree.

  • Copy .env automatically with a .worktreeinclude file (same syntax as .gitignore). Claude Code and the Codex app both read it.

  • Give each worktree its own dev-server port, or two sessions will fight over localhost:3000.

  • Get notified when a session needs input with a Notification hook, so you don't have to check every tab.

Why worktrees and not just more terminal tabs

A git worktree is a second (or tenth) checkout of the same repository, in its own folder, on its own branch, sharing one .git. Each session edits its own files, so:

Opening three tabs in the same folder gives you none of that. Subagents are a different thing. They split work inside one session and report back to it. Worktrees are for separate tasks you want to keep apart.

Method 1: Claude Code's built-in worktrees

Claude Code has worktree support built in:

claude --worktree feature-auth     # or: claude -w feature-auth
claude --worktree                  # no name: Claude picks one, like bright-running-fox
claude --worktree "#1234"          # start from a pull request

What happens:

Cleanup is mostly automatic. When you exit, a clean, unnamed worktree is removed along with its branch. If there's work in it, Claude asks whether to keep it. To come back later, run claude --worktree <name> --resume.

Add the folder to .gitignore so worktrees never show up as changes in your main checkout:

.claude/worktrees/

You can also ask mid-conversation. Say "work in a worktree" and Claude moves the session into one. For big mechanical changes, /batch splits the work across 5 to 30 subagents, each in its own worktree.

Method 2: plain git worktrees (any agent)

If you'd rather control the folders yourself, or you use several different agents, plain git does the same job:

git worktree add ../app-feature-a -b feature-a   # new folder, new branch
cd ../app-feature-a && claude                    # start the agent there

git worktree list                                # see them all
git worktree remove ../app-feature-a             # done: remove it
git worktree prune                               # clean up folders you deleted by hand

Two rules git enforces:

Method 3: Codex

Codex CLI has a flag for the same thing:

codex --worktree                          # new interactive session in a managed worktree
codex exec --worktree "implement the next step"
codex fork <SESSION_ID> --worktree        # branch an existing session into a worktree

The Codex app creates worktrees under $CODEX_HOME/worktrees, keeps the 15 most recent by default, and lets you move a chat between your local checkout and a worktree. To pick a session up again, use codex resume, or codex resume --last for the most recent one. Add --all to see sessions from other folders.

The three things that break

1. Dependencies and .env files

A worktree is a fresh checkout. Gitignored files don't come along, so node_modules, build caches and your .env are missing.

.env .env.local

2. Ports

Three sessions each running npm run dev all want localhost:3000. The second one fails or moves to some random port, and now you don't know which browser tab belongs to which branch. Common fixes:

Writing the port into the session's name (3002 checkout) makes it obvious which tab is which.

3. Knowing who needs you

With several sessions, the bottleneck becomes you: one session waits on a permission prompt for ten minutes while you watch another one. People on Hacker News say their practical limit is two or three sessions for exactly this reason. Open GitHub issues ask for a way to see which session is blocked without checking every tab.

Claude Code can tell you. Add a Notification hook to ~/.claude/settings.json (macOS example):

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Claude Code also has agent view (research preview): claude agents lists every background session with its state (Working, Needs input, Idle, Completed…). Start one with claude --bg "prompt", or send the current one there with /bg.

Naming and resuming sessions

Ten sessions called "Claude Code" are impossible to tell apart. Name them:

Don't resume the same session in two terminals. Both write to one transcript and it gets mixed up. Use /branch or --fork-session to split a conversation instead.

Tools that manage many sessions

If juggling terminal tabs gets old, these apps and tools wrap the same idea (one agent per worktree) in an interface:

Watch the quota

Parallel sessions spend your plan faster. That isn't a bug, it's the trade. Claude Code's docs put it plainly: running several sessions or subagents at once multiplies token usage. Background sessions count against your subscription just like interactive ones. On Pro or Max, the 5-hour window and the weekly limit both run out sooner. Check where you stand with /usage before starting a big parallel push.

Where Aki fits

Aki is a free macOS app built by someone running ten-plus Claude Code sessions at once, for the two things that get hard at that scale:

It's Mac-only (Apple Silicon, macOS 14+). Typing straight into a session's tab works with Orca, and other terminals read marks through Aki's MCP server or the aki CLI. Marks stay on your Mac. There's no account.

FAQ

Can I run multiple Claude Code sessions at the same time?

Yes. Run each one in its own git worktree (claude --worktree <name>) so they don't edit the same files. Each worktree has its own folder and branch.

What does claude --worktree do?

It creates a worktree in .claude/worktrees/<name>/ on a new branch called worktree-<name> and starts Claude in it. When you exit, a clean, unnamed worktree is removed automatically. If there's work in it, Claude asks whether to keep it.

Why is my .env missing in the worktree?

A worktree is a fresh checkout, and gitignored files don't come along. List them in a .worktreeinclude file at the project root and Claude Code (and the Codex app) will copy them into new worktrees.

How do I run several dev servers from different worktrees?

Give each worktree its own port, for example a different PORT in each .env. Otherwise they all try to use the same localhost port.

How do I know when a Claude Code session needs input?

Add a Notification hook in ~/.claude/settings.json that shows a desktop notification or plays a sound. Or open claude agents to see every background session's state.

Does Codex support worktrees?

Yes. codex --worktree starts a session in a new managed worktree, and the Codex app manages worktrees under $CODEX_HOME/worktrees.

Sources