Claude Code Worktree Context Loss Is Real — Here Are 3 Workflows That Actually Help

If you've been following the Claude Code GitHub issues lately, you've probably seen #28769 pop up: --resume flag loses context when --worktree option was used. It has a bunch of upvotes and a long thread of people saying "yep, same here."

I've been there. You spin up a worktree for a feature branch, do some solid work with Claude, then try to resume your session later — and Claude has no idea what you were doing. All that context about your architecture decisions, the edge cases you discussed, the specific approach you agreed on — gone.

Here are three workflows I've settled on that actually help.

---

Why Worktrees Break Context Recovery

Before getting into the workflows, it helps to understand what's happening.

Claude Code sessions are tied to a working directory. When you use --worktree, you're operating in a different directory than your main checkout. The session state (compaction summaries, conversation history) lives relative to that path. When you try to --resume from your main directory, or switch between worktrees, Claude can't find the right session to pick up.

This is a known issue — the GitHub thread on #28769 shows the core problem is that session identifiers don't account for the worktree path. Until there's a native fix, you have to work around it.

---

Workflow 1: The Git Anchor Method

The most reliable thing I've found is treating git commits as explicit context checkpoints — not just for code, but for session state.

Before ending any meaningful Claude session, I run:

# Commit your actual work
git add -A
git commit -m "feat: implement user auth flow

Session context:
- Decided on JWT over sessions for stateless scaling
- Using refresh token rotation (see auth/tokens.ts)
- Left TODO: rate limiting on /api/auth/login
- Next: add middleware to protected routes"

The commit message carries the context. When I resume — in any worktree, on any machine — I read the last few commits and feed that to Claude:

# When resuming
git log --oneline -5
# Then tell Claude: "Here's where we left off..." and paste the relevant commit messages

It's manual, but it's reliable. The commit log is your persistent memory layer.

---

Workflow 2: Worktree-Specific CLAUDE.md Files

Claude Code reads CLAUDE.md files for project context. Most people have one at the repo root. The trick is: you can have one per worktree.

Here's my setup:

# Create a worktree-specific context file
cat > .git/worktrees/feature-auth/CLAUDE.md << 'EOF'
# Feature: User Authentication (Branch: feature/auth)

## Current State
Working on JWT implementation. Core logic done in auth/tokens.ts.

## Decisions Made
- Chose HS256 for internal services (RS256 overkill for our scale)
- Refresh tokens stored in httpOnly cookies
- Access tokens: 15min expiry

## In Progress
- [ ] Rate limiting middleware
- [ ] Token revocation list
- [ ] Integration tests for refresh flow

## Known Issues
- Edge case with concurrent refresh requests not handled yet
EOF

Wait — that path won't work directly. Claude Code reads CLAUDE.md from your working directory. So the pattern that actually works is putting the file in the worktree root:

# In your worktree directory
echo "# Worktree Context: feature/auth
...your session notes..." > CLAUDE.md

# Add to .gitignore so it doesn't pollute the branch
echo "CLAUDE.md" >> .gitignore

Now every time Claude starts in that worktree, it reads your context file. You're rebuilding the session state automatically.

---

Workflow 3: Session Snapshot Scripts

This one takes a bit of setup but pays off fast if you jump between multiple worktrees.

I have a small shell script called claude-snapshot:

#!/bin/bash
# claude-snapshot: Save session context before switching worktrees

SNAPSHOT_DIR="$HOME/.claude-snapshots"
WORKTREE_NAME=$(basename $(pwd))
SNAPSHOT_FILE="$SNAPSHOT_DIR/$WORKTREE_NAME-$(date +%Y%m%d-%H%M).md"

mkdir -p "$SNAPSHOT_DIR"

cat > "$SNAPSHOT_FILE" << EOF
# Session Snapshot: $WORKTREE_NAME
Date: $(date)
Branch: $(git branch --show-current)
Last commit: $(git log --oneline -1)

## Recent Changes
$(git diff --stat HEAD~3 HEAD 2>/dev/null || echo "N/A")

## Session Notes
EOF

# Open editor for manual notes
${EDITOR:-nano} "$SNAPSHOT_FILE"

echo "Snapshot saved to: $SNAPSHOT_FILE"

And a companion claude-restore that prints the latest snapshot for a given worktree:

#!/bin/bash
# claude-restore: Print latest snapshot for current worktree

SNAPSHOT_DIR="$HOME/.claude-snapshots"
WORKTREE_NAME=$(basename $(pwd))

LATEST=$(ls -t "$SNAPSHOT_DIR/$WORKTREE_NAME"*.md 2>/dev/null | head -1)

if [ -z "$LATEST" ]; then
  echo "No snapshot found for $WORKTREE_NAME"
  exit 1
fi

echo "=== Latest snapshot: $LATEST ==="
cat "$LATEST"

Run claude-snapshot before you stop work. Run claude-restore and paste the output to Claude when you resume. Takes about 30 seconds.

---

The Bigger Problem: Skill Discovery

There's another issue in the Claude Code tracker right now — #28782 about making Skills discoverable via a UI dropdown. This one is interesting because it points to a pattern: as these tools get more powerful, the tooling around them (session management, skill organization, context persistence) hasn't kept up.

That's actually what drew me to Mantra. It's a tool built around exactly this gap — it handles the git anchor system automatically (Replay), gives you a unified console for managing Claude Code and other AI CLI tools (Control), and has session-aware context tracking. I use the manual workflows above when I'm on a machine without it, but Mantra handles a lot of this overhead when I'm in my normal setup.

Worth a look if you're spending more time fighting session loss than writing code.

---

What Actually Matters

The three workflows above — git anchor commits, worktree CLAUDE.md files, and session snapshots — address the same root problem: AI coding tools don't have persistent memory across sessions by default. You have to build that persistence yourself.

Until the --resume + --worktree bug gets fixed natively, these are the practical options. The git anchor method is the one I'd start with — it has zero dependencies and your context is version-controlled alongside your code.

If you've found other approaches that work, drop them in the comments. This is a problem enough people are hitting that I'd love to see more solutions floating around.

Comments

[Kai Alder]

The git anchor method is basically what I ended up doing too, except I keep a SESSION.md file in the repo root that I update before stopping work. Claude picks it up automatically on next launch which saves the copy-paste step.

Something like:

## Last Session
- Working on: auth middleware
- Blocked by: need to figure out token refresh race condition
- Next step: write integration test for /api/auth/refresh

One thing worth adding — if you're using worktrees heavily, you can symlink your .claude directory between them so session history at least has a chance of surviving. Not perfect but it helped me a couple times.

Has anyone tried using --session-id with a deterministic name based on the branch? Like claude --session-id "feature-auth" so you always get the same session back regardless of directory?

[Harsh]

BRO. The #28769 pain is SO real. I've lost count of how many times I've explained my entire architecture to Claude, switched branches, come back, and gotten 'Hello! How can I help you today?' like we're meeting for the first time. 💀 Workflow #2 (context persistence strategy) is exactly what I needed — thank you for this. Quick question: do you ever run into token limits when you're pasting 3-4 days of context back in? That's been my struggle with the copy-paste approach.

[Matthew Hou]

The git-anchor method is what I've settled on too, though I frame it slightly differently: commit messages as the persistence layer for intent, not just code state. The CLAUDE.md-per-worktree idea is clever. I've been doing something similar but at the project root — a single CLAUDE.md that includes a 'current branch context' section I update manually. Your approach of putting it in the worktree directory is cleaner because it can't drift out of sync with the branch you're actually on. One addition that's helped me: I keep a DECISIONS.md alongside CLAUDE.md that logs architectural choices with the reasoning. When context is lost, the decisions file recovers intent faster than replaying conversation history.

[Clemens Herbert]

The point about AI tools being skill multipliers rather than replacements is spot on.

Bookmarking this immediately 📌 This is why I love dev.to 🧡