# How do I run parallel Claude Code sessions with git worktrees without them overwriting each other?

**Short answer:** Give each session its own git worktree: a separate working directory on its own branch that shares the repository's history. Two Claude Code sessions in the same folder edit the same files and step on each other; two sessions in two worktrees can't. Claude Code builds this in: run claude --worktree feature-auth (or -w) in one terminal and claude --worktree fix-login in another, and each gets a checkout under .claude/worktrees/ on a new branch named worktree-<name>. A worktree is a fresh checkout, so install dependencies in it and copy gitignored files such as .env with a .worktreeinclude file. Keep the tasks independent (different files or areas), give each session its own dev-server port and test database, and merge the branches back one at a time through review and CI, the same as work from two people.

## Checklist
1. Commit first: a worktree is created from an existing commit, so a repository with no commits can't make one. Add .claude/worktrees/ to .gitignore so worktree contents don't show up as untracked files in your main checkout.
2. Start each session in its own worktree: claude --worktree <name> (or -w). Running the same name again reopens that worktree; omitting the name makes Claude generate one.
3. To start from a specific existing branch or put the worktree outside the repository, use git directly: git worktree add ../project-feature-a -b feature-a, then cd there and run claude. List them with git worktree list.
4. Set up each worktree like a fresh clone: install dependencies, and list gitignored files the app needs (.env, .env.local) in a .worktreeinclude file at the project root so Claude Code copies them into every new worktree. Only files that match and are gitignored are copied.
5. Avoid shared-resource collisions git can't see: give each worktree its own dev-server port, its own local or test database (or schema), and its own build cache when the tool keeps one outside the folder. Never point parallel sessions at production.
6. Split work so sessions touch different files: one feature per worktree, not two sessions on the same component. Overlapping edits become merge conflicts later instead of overwrites now, which is better, but still work.
7. By default new worktrees branch from the repository's default branch on the remote; set worktree.baseRef to "head" in settings if a session must start from your unpushed local work.
8. Merge back one branch at a time through a pull request with CI, rebasing the next branch on the updated main. Then clean up: git worktree remove <path>, or let Claude remove a clean worktree when you exit the session.

## What a worktree shares and what it doesn't
- Each worktree has its own files, branch and index, so edits and staged changes in one don't appear in another.
- All worktrees share one .git directory: commits, branches, stashes and remotes are common, and git won't check out the same branch in two worktrees at once.
- Outside git, nothing is isolated: ports, databases, Docker containers, caches in your home directory and the credentials in your environment are shared, so isolate those yourself.

## Worktrees vs subagents
- Worktrees isolate file edits between sessions you drive yourself, each with its own context and conversation.
- Subagents split one task inside a session. A custom subagent can also run in its own temporary worktree by adding isolation: worktree to its frontmatter, so parallel refactors don't collide.
- More parallel sessions means more diffs to review. Two or three focused sessions you actually review beat many you merge unread.

## Ask Rightshold (free, no key)
Add the MCP server https://www.rightshold.com/mcp to Claude, Cursor, ChatGPT, Grok or VS Code (one-click setup: https://www.rightshold.com/start?ref=seo), then ask: "My parallel Claude Code branches added these packages. Are their licenses OK for our commercial, closed-source app before I merge?"

```json
{
  "tool": "check_rights_batch",
  "arguments": {
    "intended_use": {
      "commercial_use": true,
      "redistribution": true
    },
    "items": [
      {
        "ref": "<package-added-in-worktree-a>",
        "license": "MIT"
      },
      {
        "ref": "<package-added-in-worktree-b>",
        "license": "<its SPDX id>"
      }
    ]
  }
}
```
- No editor? Run curl -fsSL https://www.rightshold.com/check.mjs | node - in each worktree. It checks the direct dependencies in package.json and sends only license ids, never your code or file names.
- license_compatibility checks whether the licenses from all branches can be combined in one product and which duties apply together.

_Rightshold does not create worktrees, run Claude Code or merge branches; worktree isolation lives in git and Claude Code. It checks the licenses of packages your sessions add._

## Sources
- [Claude Code docs: Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees)
- [Claude Code docs: Common workflows (parallel sessions)](https://code.claude.com/docs/en/common-workflows)
- [Git documentation: git-worktree](https://git-scm.com/docs/git-worktree)
- [Claude Code docs: Subagents](https://code.claude.com/docs/en/sub-agents)

## Related
- [How to make Claude Code reuse your existing components](https://www.rightshold.com/answers/how-to-make-claude-code-reuse-your-existing-components)
- [How to stop an AI coding agent from deleting your production database](https://www.rightshold.com/answers/how-to-stop-an-ai-coding-agent-from-deleting-your-production-database)
- [How to check licenses of all npm dependencies before shipping](https://www.rightshold.com/answers/how-to-check-licenses-of-all-npm-dependencies-before-shipping)

_Not legal advice. Updated 2026-10-29. JSON: https://www.rightshold.com/answers/how-to-run-parallel-claude-code-sessions-with-git-worktrees.json_