deckerClaude Code Worktree Context Loss Is Real — Here Are 3 Workflows That Actually Help If...
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.
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.
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.
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.
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.
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.
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.