stegasoo/docs/CLAUDE_WORKTREES.md

Using Claude Code with Git Worktrees — A Stegasoo Guide

What is a worktree?

A git worktree is a second (or third, or fourth...) copy of your repo that shares the same .git history but lives in its own folder with its own branch. Think of it like opening the same project in a parallel universe — you can hack on a feature in one worktree while keeping main pristine in another.

Claude Code has built-in worktree support, so you don't need to memorize any git commands.

Why bother?

• Safety net: Your main branch stays untouched. If Claude's changes go sideways, just delete the worktree — zero damage.
• Easy A/B comparison: Keep the original code open in one editor tab, Claude's changes in another.
• Parallel work: You can keep working in main while Claude tinkers in a worktree.
• Clean PRs: The worktree branch becomes your PR branch with no stray changes mixed in.

The 30-second version

1. Ask Claude to work in a worktree
2. Claude creates an isolated copy and works there
3. When done, you either merge or throw it away

That's it. Everything below is details.

---

How to start a worktree session

Option A: Ask Claude directly

Just tell Claude you want to work in a worktree:

> Let's work in a worktree for this
> Start a worktree called "dct-refactor"
> Can you make these changes in an isolated worktree?

Claude will use EnterWorktree behind the scenes and switch into it automatically.

Option B: Use the slash command

> /worktree

This drops you into a fresh worktree immediately.

Option C: Tell Claude to launch an agent in a worktree

If you want Claude to do something in the background without touching your working directory:

> Run the tests in a worktree so we don't mess up my local state

Claude can spin up a sub-agent with isolation: "worktree" — it gets its own copy and reports back.

---

Where do worktrees live?

Claude puts them in:

.claude/worktrees/<name>/

This directory is inside your repo but ignored by git, so it won't pollute your commits.

What happens inside a worktree?

The worktree is a full checkout of your repo on a new branch. Claude's working directory switches to it, so all file reads, edits, and commands happen there — not in your main checkout.

Important for Stegasoo: The first thing you (or Claude) should do in a fresh worktree is:

pip install -e ".[dev]"

This points your editable install at the worktree's source code instead of your main checkout. Without this, pytest will test the wrong copy of the code.

---

Real-world examples

Example 1: Feature work

You:    I want to add lz4 as a default compression option. Let's use a worktree.
Claude: *creates worktree, switches to it*
Claude: *installs dev deps, makes changes, runs tests*
Claude: All tests pass. Ready to merge or open a PR.
You:    Looks good, make a PR.
Claude: *pushes branch, creates PR*

Example 2: Risky refactor

You:    Refactor the crypto module to split KDF logic into its own file.
        Do it in a worktree so I can review before touching main.
Claude: *creates worktree "refactor/split-kdf"*
Claude: *does the refactor, runs tests*
You:    Hmm, I don't love the approach. Throw it away.
Claude: *removes worktree — main is untouched*

Example 3: Investigate a bug without side effects

You:    Something's wrong with DCT encoding on large images.
        Can you investigate in a worktree? I've got uncommitted work here.
Claude: *creates worktree, adds debug logging, runs tests*
Claude: Found it — the block size calculation overflows at >16MP.
        Here's the fix. Want me to apply it to main?

---

When to use a worktree vs. just editing in place

Situation	Worktree?	Why
Quick one-file fix	No	Overkill — just edit directly
Multi-file refactor	Yes	Easy to discard if it goes wrong
Touching security-critical code (crypto.py, steganography.py, etc.)	Yes	Extra safety for sensitive changes
Experimental / "let's try this" work	Yes	Zero-cost throwaway
You have uncommitted changes you don't want to stash	Yes	Worktree won't touch your working tree
Adding a single test	No	Low risk, just do it

---

Cleaning up

If you merged or created a PR

The worktree served its purpose. Clean up:

git worktree remove .claude/worktrees/<name>

Or ask Claude:

> Clean up the worktree

If you want to throw everything away

Same command — removing the worktree deletes the directory and its branch reference. Your main branch is completely unaffected.

If Claude's session ends

When a Claude Code session ends while in a worktree, you'll be prompted to keep or remove it. If you keep it, you can resume later:

cd .claude/worktrees/<name>
# pick up where you left off

---

Branch naming in worktrees

Follow the same conventions as the rest of the project:

Type	Branch name	Example
Feature	feature/description	feature/batch-progress-bars
Bug fix	fix/description	fix/dct-overflow-large-images
Docs	docs/description	docs/api-examples
Refactor	refactor/description	refactor/split-crypto-module

When Claude creates a worktree automatically, it generates a random branch name. You can rename it before pushing:

git branch -m <old-name> feature/my-better-name

---

Troubleshooting

"I ran pytest but it's testing the old code"

You forgot to install in the worktree:

pip install -e ".[dev]"

"I can't find my worktree"

git worktree list

This shows all worktrees and their paths.

"I accidentally deleted the worktree folder without removing it from git"

git worktree prune

This cleans up stale worktree references.

"I want to switch back to my main checkout"

If you're in a Claude Code session that entered a worktree, the session stays in the worktree until it ends. Start a new session to go back to your main checkout, or:

cd /home/alee/Sources/stegasoo

---

TL;DR

1. Say "use a worktree" when asking Claude to make changes
2. Claude works in an isolated copy — your main is safe
3. Merge the good stuff, trash the bad stuff
4. Never think about it again until next time