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.jsonl

Format: 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 -r shows "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_EOF

Reference Documentation

For detailed diagnostic steps and solutions, see:

• Troubleshooting Guide - Detailed diagnostic procedures and fixes

Troubleshooting

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. 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.