How to run several Claude Code sessions in parallel without them stepping on each other

One Claude Code session is a pair programmer. Four of them is a small team, and a team needs a little structure, or you spend the afternoon untangling two agents that edited the same file.

This is the setup that works: plain git and tmux first, then the same thing with a desktop app if you'd rather not manage it by hand.

What goes wrong when you just open more terminals

Three things, in this order:

1. Collisions. Two sessions in the same folder edit the same files. One agent's half-finished change lands in the other's test run, and neither understands why.
2. Lost attention. A session stops to ask a question or for permission, and you don't notice for twenty minutes because it's in tab six.
3. Lost sessions. You close a terminal, or your laptop restarts, and the session in it is gone (you can resume the conversation, but the work stopped).

Each has a simple fix.

1. One task per session, one worktree per task

A git worktree is a second working folder for the same repository, on its own branch. Give every session its own, and collisions disappear: each agent edits its own copy of every file.

# from your main checkout
git worktree add -b fix-login ../myapp-fix-login
git worktree add -b add-export ../myapp-add-export
git worktree add -b flaky-tests ../myapp-flaky-tests

Then start one session in each:

cd ../myapp-fix-login && claude

Three things catch people out:

• Untracked files aren't copied. Your .env stays in the main checkout. Copy it in, or keep a small script that does (cp .env ../myapp-fix-login/).
• Dependencies aren't there either. Each worktree needs its own node_modules (or virtualenv). A package manager with a shared store, such as pnpm, makes that a few seconds instead of minutes.
• Ports collide. Two dev servers on port 3000 won't both start. Give each worktree its own PORT, and its own COMPOSE_PROJECT_NAME if you use Docker Compose.

When a task is done, review its branch like a teammate's pull request, merge it, and clean up:

git worktree remove ../myapp-fix-login
git branch -d fix-login

git worktree list shows what's still around, and git worktree prune tidies up folders you deleted by hand.

2. Give each session a name and a place

tmux turns a pile of terminals into something you can scan. One window per task, named after it:

tmux new -s agents -n fix-login -c ../myapp-fix-login
# inside tmux:
tmux new-window -n add-export -c ../myapp-add-export
tmux new-window -n flaky-tests -c ../myapp-flaky-tests

Start claude in each window. The window names in the status bar are now your task list, and detaching (Ctrl-b d) leaves every session running; tmux attach -t agents brings them back. That also fixes problem 3: closing the terminal no longer ends anything.

3. Know which one needs you

Claude Code waits when it needs an answer or a permission, and a waiting session does nothing. Two habits help:

• Use Claude Code's hooks to run a command when it needs your input (the Notification hook), such as a desktop notification or a sound, so a waiting session reaches you instead of the other way round.
• Set each session's permission mode to match its task. A well-scoped task with good tests can run with fewer questions; a session touching production config should ask about everything.

4. Mind the shared limits

Every session runs on the same Claude plan, so parallel sessions share its usage limits. Five sessions burn through them five times as fast. Start with two or three, and add more once you know how your plan holds up.

The same setup on one board

I build Moontors, a free desktop app that does the above for you, so take this part with that in mind.

Each session is a card on one board that streams its agent's work as it happens. Turning on Run in a new worktree when you create a session makes the worktree, copies in the untracked files your project lists (such as .env), and asks before removing anything when you archive it. The header counts the sessions waiting for you, and a click takes you to the next one; Allow and Deny are right in the transcript. The sessions run in a background service, so closing the window doesn't stop them, and the Android and iPhone apps can answer them away from your desk.

It runs Codex and Gemini CLI too, beside Claude Code, on macOS, Windows and Linux, and needs no account of its own. The step-by-step version of this article is in its docs: How to run several Claude Code sessions in parallel.

Either way, the rules are the same: one task per session, a worktree per task, a name for each, and a way to hear when one needs you.

---

AI did the writing, I did the reading, and we both took credit.