Claude Code Git and Parallel Workflows: Branches, Worktrees, Subagents, and Safe Integration

Parallel Claude Code sessions can shorten independent work. They can also make two agents edit the same file, test different repository states, or report success against commits that never reach the integration branch. Git protects history, but it does not decide ownership or prove that combined changes work.

The reliable pattern is to separate three concerns: coordination decides who owns each task, worktrees isolate file mutations, and an integration lane verifies the combined result. Use parallelism only when the dependency graph supports it.

This guide reflects the official Claude Code, Git, and GitHub CLI documentation checked on August 9, 2026. Worktree and agent behavior has changed across recent Claude Code versions, so confirm the installed client’s documentation before automating cleanup or resumption.

Choose the smallest concurrency model

Claude Code offers several forms of parallel work. They solve different problems:

Mechanism	Best use	File isolation	Coordination
One session	One tightly coupled implementation	One working tree	Conversation and task list
Subagent	Bounded research, review, or delegated task	Shared by default; optional worktree	Parent receives a result
Conversation fork	A side path that needs the parent’s context	Shared by default; optional worktree	Fork inherits the conversation
Agent team	Teammates that communicate and share tasks	Not automatically a separate Git branch	Team lead and shared task list
Separate worktree session	Independent implementation with its own branch	Yes	External plan, PR, or human integrator

Subagents are not inherently read-only. Each starts with an isolated context, a selected tool set, and independent permissions; it may write when its tools and task allow that. Set isolation: worktree when a writing subagent must not touch the parent checkout.

Agent teams are currently experimental and disabled by default. They are useful when teammates must communicate directly, but their extra coordination and token cost are not justified for two sequential edits. A simple main session plus one focused reviewer is often clearer.

Draw the dependency graph before starting agents

Split work by independently verifiable outcome, not by an arbitrary file count. For each task, record:

its input commit;
the files or subsystem it owns;
interfaces it may consume but not change;
the expected output commit or report;
focused and integration checks;
the task that is allowed to integrate it.

A useful split looks like this:

Task A: define the schema and tests
  ↓ published interface
Task B: implement importer      Task C: update documentation
  ↓ code commit                  ↓ content commit
Integration: merge A → B → C, then run the full suite

Tasks B and C may run together only after A’s interface is stable. Two agents that both need to revise the schema are not independent, even if they start in different directories.

Do not parallelize a debugging chain where each experiment depends on the previous result. One agent should own the hypothesis loop so rejected explanations and observed evidence remain coherent.

Protect the starting state

Before creating a branch or worktree, inspect the repository:

git status --short
git branch --show-current
git log -5 --oneline
git worktree list

Uncommitted changes belong to their author. Do not let Claude reset, clean, stash, stage, or overwrite them merely to obtain a clean tree. Commit the intended base, create a new clean worktree, or explicitly exclude owned paths.

Also fetch and identify the real default branch before assuming main:

git remote show origin
git fetch origin

If a task must start from in-progress local commits, name that dependency. Claude Code’s worktree configuration supports a current-HEAD base, but an explicit commit SHA makes the handoff easier to audit.

Start an isolated Claude Code worktree

Claude Code can create and enter a worktree directly:

claude --worktree feature-auth

By default, it creates a checkout below .claude/worktrees/feature-auth/ on a new branch. Add .claude/worktrees/ to .gitignore. A worktree is a fresh checkout, so initialize dependencies there and do not assume untracked files from the main checkout exist.

For a specific base branch or a directory outside the repository, use Git directly:

git worktree add ../project-feature-auth -b feature/auth origin/main
cd ../project-feature-auth
claude

Each worktree has separate files and an independent HEAD, but linked worktrees share repository history and parts of Git administration. A destructive Git command in the wrong directory can still affect shared refs. Isolation reduces edit collisions; it does not make every Git command harmless.

Claude Code now enforces additional isolation for sessions it recognizes as worktree sessions: file tools and shell commands aimed at the protected main checkout are blocked. Keep the client current, but still review paths and commands. Do not build a safety case around one client check alone.

Decide what local state follows a worktree

Tracked files appear in every checkout. Ignored and untracked files do not. That is usually desirable: a feature worktree should not inherit production credentials or incidental build output.

Claude Code supports .worktreeinclude for selected ignored files. Use it narrowly. Copying .env into every agent checkout expands the number of processes and prompts that can access its secrets. Prefer a development-only configuration or short-lived credentials with minimum scope.

Dependencies also require a policy. Options include a fresh deterministic install, a safe shared cache, or a generated environment bootstrap. Do not symlink mutable build output across worktrees when simultaneous commands can corrupt or invalidate one another.

Record the setup command in project instructions:

## Worktree setup

- Install: `npm ci`
- Focused test: `npm test -- --run src/auth`
- Required checks: `npm run lint && npm run check && npm test -- --run`
- Never copy production `.env` files into agent worktrees.

Give every writer exclusive ownership

A worktree prevents two sessions from changing the same physical checkout, but it does not prevent two branches from editing the same logical lines. Assign exclusive ownership where possible:

Agent A owns src/auth/** and tests/auth/**.
Agent B owns docs/auth/** only.
Neither changes package.json, the schema, or shared test helpers.
If one of those changes becomes necessary, stop and report it to the integrator.

For a custom subagent that writes, use worktree isolation in its definition:

---
name: migration-worker
description: Applies one approved mechanical migration and verifies it
isolation: worktree
---

Read the task brief first. Change only the named paths, run the focused checks,
commit the result, and report the commit SHA and remaining concerns.

The parent should receive a compact handoff, not a transcript dump: status, commit SHA, tests, exact changed paths, and blockers. The integrator must be able to reproduce the result from Git.

Separate implementation from review

The same session that wrote the patch has already committed to its assumptions. Use a fresh review context when the change is material. The reviewer should receive:

the original requirements;
the exact base and head commits;
a complete diff, including new files;
the implementer’s verification report;
repository-wide constraints relevant to the task.

Review in two passes. First check specification compliance: did the patch implement the requested behavior and nothing materially different? Then check quality: correctness, error handling, security boundaries, maintainability, and test strength.

For a failed review, return precise findings to the same implementation lane. Do not let multiple fix agents race on one branch. Re-review the fix diff and the affected behavior before integration.

Integrate commits in dependency order

The integration lane should remain clean and have one owner. Apply work in dependency order using the least surprising Git operation. A small independent commit can be cherry-picked; a feature branch may be merged through a pull request. Whatever method you choose, preserve reviewable boundaries.

Before applying a worker commit:

git show --stat <commit>
git diff --check <base>..<commit>
git diff --name-only <base>..<commit>

After integration, run checks on the combined tree. Passing tests on two branches do not prove their union passes:

npm run lint
npm run check
npm test -- --run
npm run build
git status --short

Treat a conflict as evidence that the tasks were not fully independent. Resolve it with domain context, then rerun the focused checks for both sides and the full integration suite. Never accept conflict markers or choose “ours” or “theirs” mechanically for code whose behavior you do not understand.

Deliver through a pull request

A pull request is the public integration boundary, not proof that the change is correct. Push the explicit branch and open a PR with the requirement, risk, and actual verification results:

git push -u origin feature/auth
gh pr create --base main --head feature/auth --fill
gh pr checks --watch

Confirm the base branch instead of copying main blindly. Review the remote diff because ignored files, untracked files, or a broad local staging command can make the pushed branch differ from the intended patch.

Do not automatically merge merely because CI is green. Green checks only cover configured checks. Require the relevant human or automated review and verify that no unrelated files, credentials, generated artifacts, or policy changes entered the PR.

Clean up without losing work

List worktrees and inspect the target before removal:

git worktree list
git -C ../project-feature-auth status --short
git -C ../project-feature-auth log --oneline --decorate -5

Remove a worktree only after its changes are committed, pushed or intentionally discarded, and integrated or otherwise preserved:

git worktree remove ../project-feature-auth
git worktree prune

Non-interactive claude -p --worktree runs do not present an exit cleanup prompt. Track those worktrees explicitly. Avoid --force until you have resolved why Git believes work remains.

A practical parallel checklist

Parallel Claude Code work succeeds when coordination is stronger than concurrency. Start with one session, add a subagent for bounded context isolation, use a worktree for independent writes, and adopt agent teams only when direct teammate coordination materially helps.

Continue with the setup guide, permissions and security, and hooks, MCP, and automation.