Skip to main content

How to Run Multiple Claude Code Sessions

Start several Claude Code agents at once without sharing one working directory.

Goal​

Run two or more Claude Code sessions on the same repository, each on its own branch and working copy, then review and merge their results independently.

Prerequisites​

  • A Git repository with a clean or committed main
  • Claude Code installed and available as claude on your PATH
  • Enough disk for one dependency install per worktree

CLI-first setup with git worktrees​

Fetch current main, then create one worktree per task:

git fetch origin

git worktree add -b agent/payments-retry ../repo-payments-retry origin/main
git worktree add -b agent/search-filters ../repo-search-filters origin/main

git worktree list

Install dependencies in each worktree if the project needs them:

npm install --prefix ../repo-payments-retry
npm install --prefix ../repo-search-filters

Start Claude Code inside each directory, in separate terminal tabs:

cd ../repo-payments-retry
claude

# other tab
cd ../repo-search-filters
claude

Give each session one task, the files it may change, and the tests it must run. Do not point two sessions at the same directory.

When a session finishes:

cd ../repo-payments-retry
git status
git diff
git push -u origin agent/payments-retry

Open a pull request, review it, and only then start another large task for the same reviewer.

Setup with Treq workspaces​

In Treq, create one workspace per task from the dashboard. Each workspace gets a directory under .treq/workspaces/ and its own bookmark. Start a Claude Code session from the workspace so the process inherits that working directory.

See Agent Sessions and Workspaces.

Common failure cases​

Both sessions share the home checkout. Symptoms include interleaved edits, unexpected git status, and agents fighting over the same file. Fix by moving each session into its own worktree before continuing.

Same branch checked out twice. Git blocks a second worktree on the same local branch. Use unique branch names per session.

Stale base after the other PR merges. Rebase the remaining worktree:

git -C ../repo-search-filters fetch origin
git -C ../repo-search-filters rebase origin/main

Orphan worktree after a killed terminal. Remove or prune it:

git worktree remove ../repo-payments-retry
# or, if the directory is already gone:
git worktree prune

Review queue overflow. Cap concurrent sessions to what you can review the same day. Unused finished branches go stale and create conflicts later.

Cleanup​

git worktree remove ../repo-payments-retry
git worktree remove ../repo-search-filters
git branch -d agent/payments-retry agent/search-filters