# Claude Code worktrees: keep parallel tasks in separate checkouts

> Source: <https://somethingbig.ai/work/claude-code-worktrees>
> Published: 2026-09-24 00:00:00+00:00

Two coding sessions should not take turns editing the same checkout and hope Git will sort it out later. Give each task a worktree: a separate working directory and branch attached to the same repository. You can inspect each change independently, then deliberately bring the useful work together.

This walkthrough creates one worktree for documentation and another for a test plan. The exercise uses Git directly so you can see the underlying isolation before launching Claude Code inside either directory. It needs Git and a terminal; the shell examples work on macOS or Linux.

## Start from a clean, committed baseline

For an existing project, run `git status --short` and decide what to do with unfinished changes first. For a disposable exercise, create a small repository:

```
mkdir receipt-lab
cd receipt-lab
git init -b main
printf '# Receipt Lab
' > README.md
git add README.md
git commit -m "Create exercise baseline"
```

The commit uses your existing Git identity. There is no remote push in this exercise. A worktree branches from a commit; it does not automatically copy the uncommitted state of your main checkout.

## Create one branch per task

```
git worktree add -b guide-docs ../receipt-docs main
git worktree add -b guide-tests ../receipt-tests main
git worktree list
```

You now have three directories. `receipt-lab` stays on `main`, `receipt-docs` uses `guide-docs`, and `receipt-tests` uses `guide-tests`. Launch Claude Code from the directory for its task, and confirm that directory before asking it to edit.

```
cd ../receipt-docs
claude
Document that amounts in Receipt Lab use integer cents.
Only change README.md. Do not commit, push, or modify another checkout.
Show the diff when finished.
```

In a second terminal, use `receipt-tests` for the separate test-plan task. Make the boundaries explicit: a worktree separates files, but both tasks can still make incompatible design choices. Agree on the function contract before they start.

## Check the separation yourself

For the disposable exercise, you can make the edits without a model:

```
printf '
Amounts use integer cents.
' >> ../receipt-docs/README.md
printf 'Check 0 and 100 percent discounts.
' > ../receipt-tests/test-plan.md
git -C ../receipt-docs status --short
git -C ../receipt-tests status --short
git status --short
```

Run those commands from `receipt-lab`. The first worktree should show the changed README, the second an untracked test-plan file, and the main checkout should remain clean. Read the main README too; it should not contain the new paragraph yet. That is the observable benefit of separate working trees.

## Review and merge one result at a time

Inspect the documentation diff, commit it in its worktree, then merge that branch from the main checkout:

```
git -C ../receipt-docs diff -- README.md
git -C ../receipt-docs add README.md
git -C ../receipt-docs commit -m "Document integer cents"
git merge --ff-only guide-docs
```

`--ff-only` refuses when Git cannot simply advance the current branch. That is a useful stop point: inspect why the histories diverged instead of hiding a merge decision inside an automated task. Review the test-plan branch separately. Parallel creation does not require parallel merging.

## What worktrees do not isolate

Processes can still share ports, databases, credentials, build caches and external services. Two development servers may both try to use port 3000. A migration script may point both checkouts at the same database. Give those resources explicit local settings; do not assume a new directory gives you a new environment.

Claude Code also provides `claude --worktree task-name`. That is convenient, but check the configured starting ref and generated directory. Use Git directly when you need an exact branch or path, as in this exercise.

## Clean up after preserving the work

For this exercise, preserve the test plan on its branch before removing the clean worktrees:

```
git -C ../receipt-tests add test-plan.md
git -C ../receipt-tests commit -m "Record discount test plan"
git worktree remove ../receipt-docs
git worktree remove ../receipt-tests
git worktree list
```

If Git refuses because a worktree has changes, inspect them. Do not add `--force` merely to silence the error. Removing a directory is not the same thing as deciding its work is disposable. Branch cleanup can be a separate reviewed step.

**What we checked:** Two scratch worktrees had independent edits while the main checkout stayed unchanged. A reviewed documentation commit fast-forwarded into main, and both clean worktrees were removed without force. These are Git isolation checks; they do not claim that external services or model decisions are isolated.

Pair separate checkouts with a narrow [reviewer](https://somethingbig.ai/work/claude-code-subagents) and a short [task handoff](https://somethingbig.ai/work/claude-code-context-window).

## Sources and version notes

Checked against the current documentation on September 24, 2026. Command availability can vary with your installed version; check `claude --version`.