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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
pip install -e ".[dev]"
```

### "I can't find my worktree"

```bash
git worktree list
```

This shows all worktrees and their paths.

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

```bash
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:

```bash
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