How to run several Claude Code sessions at once: worktrees, tmux and apps

Why parallel sessions collide

Two agents in one folder share one set of files and one checked-out branch, so each sees, and can overwrite, the other’s half-finished work. A folder has one branch checked out at a time: if one agent switches branch, the files change under the other. If both edit the same file, one overwrites the other; Anthropic’s own guide to agent teams warns that two agents editing the same file “leads to overwrites”. And a test run in one session picks up the other’s unfinished edits, so a failure no longer tells you whose change broke it.

The fix is not fewer agents but separate checkouts. A git worktree gives each session its own folder and its own branch while sharing one repository’s history, so the agents work side by side and you merge their branches as you would anyone else’s.

Give each session its own git worktree

A worktree is a second working folder for the same repository, on its own branch. Commits made in any worktree land in the one shared repository, so there is nothing to push between them. Four commands cover daily use:

# a new folder beside the repo, on a new branch called auth
git worktree add ../myapp-auth -b auth

# every worktree, with the commit and branch it has checked out
git worktree list

# delete the folder once its branch is merged
git worktree remove ../myapp-auth

# forget worktrees whose folders you deleted by hand
git worktree prune

Then start an agent in each folder, in its own terminal tab or window:

cd ../myapp-auth && claude

Three rules from git’s documentation are worth knowing before you rely on this:

• Without -b, git worktree add ../myapp-auth creates a branch named after the folder, myapp-auth.
• Git refuses to check out a branch that another worktree already has checked out. That is the protection you want: two agents can never be on the same branch by accident.
• git worktree remove only removes a clean worktree. One with untracked or modified files needs --force, which deletes that work, so commit or copy out anything you want first.

The gotcha: .env and other untracked files stay behind

A new worktree is a fresh checkout of tracked files only, so your .env, local config and installed dependencies are not there. Claude Code’s documentation says so directly: untracked files like .env or .env.local from your main repository are not present. It is one of the complaints that come up most about worktree-based tools, and the cause of many “it works in the other session” failures.

Three ways round it:

• Copy by hand when you create the worktree, for example cp .env ../myapp-auth/, then install dependencies there with npm install or your project’s equivalent.
• Let Claude Code copy them. A .worktreeinclude file at the project root, in .gitignore syntax, lists files to copy into every worktree Claude Code creates. Only files that match a pattern and are gitignored are copied, so tracked files are never duplicated. The Codex app reads a .worktreeinclude file too.
• Use the app’s setting if you run agents through one: Conductor, for example, has a “Files to copy” setting for the same job.

# .worktreeinclude, at the repository root
.env
.env.local
config/secrets.json

One more that surprises people: if you set up Git LFS with git lfs install --local, a worktree Claude Code creates holds LFS pointer files rather than the real files, because it skips filter drivers defined in the repository’s own config. Run git lfs pull inside the worktree to fetch them.

Claude Code’s own ways to run in parallel

Claude Code has four built-in options, from you driving every session to Claude coordinating a team: --worktree, agent view, subagents and agent teams. All of them run Claude sessions only; none of them starts Codex or another CLI.

Worktree sessions

claude --worktree <name> creates the worktree under .claude/worktrees/<name>/ at the repository root, on a new branch called worktree-<name>, and starts Claude in it; leave out the name and Claude invents one. New worktrees branch from the repository’s default branch; set worktree.baseRef to "head" in settings to start from your current work instead, or pass a pull request (claude --worktree "#1234") to start from that. Add .claude/worktrees/ to .gitignore, and run claude once in the repository first: an interactive worktree session needs the folder trusted.

When you exit, a clean, unnamed worktree is removed with its branch. One with work in it prompts you to keep or remove it, and Claude Code prints the claude --worktree <name> --resume command to come back to it.

Agent view

claude agents opens one screen for sessions running in the background: what each is doing, which need your input, and which are done. It is a research preview, so the interface may change. Anthropic is unusually direct about the cost: background sessions use your subscription “the same as interactive sessions, so running ten agents in parallel uses quota roughly ten times as fast as running one.”

Agent teams

Agent teams let a lead session spawn teammates that message each other and share a task list. They are experimental and off by default, and teammates are not isolated in worktrees, so the work has to be split so each owns different files. Teammates can run inside your main terminal, or each in its own split pane; split panes need tmux, or iTerm2 with its it2 command-line tool, and are not supported in VS Code’s integrated terminal, Windows Terminal or Ghostty. Anthropic estimates teams use about seven times the tokens of a standard session when teammates run in plan mode, and suggests starting with three to five teammates.

Anthropic’s overview also lists dynamic workflows and cloud projects as ways to run work in parallel. This guide sticks to sessions on your own machine.

Keep sessions alive with tmux

tmux keeps each agent running after you close the terminal window, and lets you come back to it later, including over SSH. tmux keeps its state in a server process, so a session you detach from carries on, and you reattach when you want to look. The default prefix key is Ctrl-b.

tmux new -s auth          # a new session called auth; start claude inside it
# Ctrl-b d                 detach: the agent keeps running
tmux ls                   # list your sessions
tmux attach -t auth       # go back to it
# Ctrl-b %                 split the window left and right
# Ctrl-b "                 split it top and bottom
# Ctrl-b c                 a new window; Ctrl-b n and Ctrl-b p move between them
tmux kill-session -t auth # end it when the work is merged

A layout that scales: one tmux session per worktree, named after its branch, so tmux ls doubles as a list of what your agents are working on.

Claude Code needs three lines in ~/.tmux.conf to behave inside tmux. Without them, Shift+Enter sends your message instead of adding a new line, and Claude Code’s desktop notifications never reach your terminal:

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Apply them to a running server with tmux source-file ~/.tmux.conf. If you use iTerm2, Anthropic suggests starting tmux with tmux -CC.

Which terminal is best for Claude Code?

Any terminal runs Claude Code. With several sessions open, the differences that matter are notifications and keys. By default Claude Code sends a desktop notification only in Ghostty, Kitty and iTerm2. Anywhere else, set preferredNotifChannel to "terminal_bell" in ~/.claude/settings.json, or add a Notification hook (below).

Two more differences show up with parallel work. Agent-team split panes need tmux or iTerm2, as above. And since version 2.1.295, Claude Code reports each session’s state (working, waiting on you, or done) to terminals that implement the OSC 7501 Program Status Protocol; inside tmux it asks tmux rather than your terminal, so start the session outside tmux if you want to see it, and background sessions report their state in agent view instead. Whether your terminal implements the protocol is in its own documentation.

Knowing which session is waiting on you

Add a Notification hook: Claude Code runs it when a session needs your approval or has finished and gone quiet, so you can leave sessions working and come back when one asks. This example, in ~/.claude/settings.json, shows a macOS notification:

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

The hook can match on the kind of notification. permission_prompt fires when an approval prompt has waited about six seconds; idle_prompt when Claude finished about 60 seconds ago and you have not typed since. Put "matcher": "permission_prompt" beside the inner "hooks" list to be told only when something needs approving. On macOS, osascript notifications come from Script Editor, which needs notification permission in System Settings; without it the command fails silently. The full walkthrough is in Claude Code hooks, explained.

What running several sessions costs

Every session draws on the same plan, so parallel work spends your limits faster; it does not make them go further. Anthropic says ten agents in parallel use quota roughly ten times as fast as one, and that agent teams use about seven times the tokens of a single session when teammates plan.

Claude’s Pro, Max and Team plans meter Claude Code in a rolling five-hour window plus weekly limits, shared with your Claude chats, and Anthropic publishes no hour or prompt numbers for either. On ChatGPT Plus, Codex has a five-hour window and weekly limits may apply; OpenAI says ChatGPT Pro “currently has no five-hour limit”.

Ways to make a plan last with several sessions open, all from Anthropic’s own cost guidance:

• give routine sessions and teammates a cheaper model, such as Sonnet, and keep Opus for the hard ones;
• run /clear between unrelated tasks, because every request carries the whole conversation;
• close sessions you are done with: scheduled tasks and goal check-ins send their context even while a session sits idle.

Current plans and limits are on each vendor’s own page, which we link rather than copy because they change often: Claude pricing and Codex pricing.

Mixing Claude Code, Codex and other CLIs

Worktrees are plain git, so any CLI works in one: Claude Code in one worktree and Codex or OpenCode in the next. A pattern developers describe often is one agent writing on its branch while another, from a different vendor, reviews it.

Codex has worktrees built in too, in the ChatGPT desktop app: each Codex chat there runs in Local, Worktree or Cloud mode. Its worktrees live in $CODEX_HOME/worktrees, start in a detached HEAD state rather than on a branch, and Codex keeps the 15 most recent by default. It copies the gitignored files listed in .worktreeinclude, the same file Claude Code reads. The Codex CLI, like OpenCode, simply runs in whichever worktree you start it in.

The difference that bites when you mix them is resuming, which works by folder in Claude Code and by session id from anywhere in Codex (above). How the CLIs compare more widely: Codex vs Claude Code and OpenCode vs Claude Code.

Apps built for running agents in parallel

If you would rather not wire worktrees, tmux and hooks together yourself, several apps do it; they differ mostly in platform, licence, and whether they are built around worktrees or around terminals. In alphabetical order, as listed on 12 October 2026:

We make one of these apps, AI Bridge, so we have left it out of the table; it is described once, in the box below. Projects in this space change quickly, so check that one is still maintained before you build your day around it.

Questions