Answers · agent safety
How do I run parallel Claude Code sessions with git worktrees without them overwriting each other?
Last updated
TL;DR: 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.
What should I check, step by step?
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 does a worktree share, and what doesn't it?
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 or subagents: which should I use?
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.
How do I ask a2ally about this (free, no key)?
Add the MCP server https://www.a2ally.com/mcp to Claude, Cursor, ChatGPT, Grok or VS Code, then ask: “My parallel Claude Code branches added these packages. Are their licenses OK for our commercial, closed-source app before I merge?”
{
"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.a2ally.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.
a2ally 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.
What are the sources?
- Claude Code docs: Run parallel sessions with worktrees
- Claude Code docs: Common workflows (parallel sessions)
- Git documentation: git-worktree
- Claude Code docs: Subagents
Related
- How to make Claude Code reuse your existing components
- How to stop an AI coding agent from deleting your production database
- How to check licenses of all npm dependencies before shipping
Not legal advice. JSON · Markdown · All answers
Get a free API key in one call
No card and no email needed. 100 free credits; the license and policy checks stay free without a key.
curl -s -X POST https://www.a2ally.com/v1/accounts/signup -H "Content-Type: application/json" -d '{"accept_terms":true}'
export A2ALLY_API_KEY=rs_... # the api_key from the reply (shown once)
curl -s https://www.a2ally.com/v1/licenses/check -H "Authorization: Bearer $A2ALLY_API_KEY" \
-H "Content-Type: application/json" -d '{"license":"MIT","intended_use":{"commercial_use":true}}'