Claude Code Session Recovery Skill
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
When to Use This Skill
Use this skill when:
- "No conversations found to resume" when running
claude -r - New conversations not creating session files
- Sessions appearing in wrong locations (
/tmp/instead of~/.claude/projects/) - Session history missing after environment changes
- IDE/terminal settings affecting session creation
- Need to migrate or recover 600+ legacy sessions
Quick Reference
Official Session Storage
Standard Location: ~/.claude/projects/
Structure:
~/.claude/projects/
├── -home-username-my-project/ # Encoded absolute path
│ └── 364695f1-13e7-4cbb-ad4b-0eb416feb95d.jsonl
└── -tmp-another-project/
└── a8e39846-ceca-421d-b4bd-3ba0eb1b3145.jsonlFormat: One JSON event per line (JSONL), UUID-based filenames
Critical Pitfall: HOME Variable
Problem
Claude Code uses $HOME environment variable to determine session storage location. If $HOME is incorrect, sessions go to wrong directory or disappear.
Symptoms
claude -rshows "No conversations found to resume"- New conversations work but files don't appear in expected location
- Sessions found in
/tmp/or other unexpected paths - Works on one machine but not another
Diagnosis
/usr/bin/env bash << 'PREFLIGHT_EOF'
# Step 1: Check current HOME
echo "Current HOME: $HOME"
# Step 2: Check system expectation
echo "Expected HOME: $(getent passwd $(whoami) | cut -d: -f6)"
# Step 3: Find where Claude is actually writing
find /tmp -name "*.jsonl" -path "*/.claude/projects/*" 2>/dev/null
PREFLIGHT_EOFReference Documentation
For detailed diagnostic steps and solutions, see:
- Troubleshooting Guide - Detailed diagnostic procedures and fixes
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| "No conversations found" | Wrong HOME variable | Verify $HOME matches expected user directory |
| Sessions in /tmp/ | HOME set incorrectly | Fix HOME in shell profile, restart terminal |
| Session files missing | Disk space or permissions | Check ~/.claude/projects/ permissions and disk |
| Wrong project sessions shown | Path encoding mismatch | Check encoded path matches current working directory |
| Sessions not persisting | File system issues | Verify write permissions to ~/.claude/projects/ |
| IDE sessions separate | Different HOME per environment | Ensure consistent HOME across terminal and IDE |
| Legacy sessions not visible | Migration not complete | See migration section in TROUBLESHOOTING.md |
| UUID filename corruption | Incomplete writes | Check for partial.jsonl files, remove corrupt ones |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.