session-recovery
Troubleshoot Claude Code session issues. Use when encountering "No conversations found" errors, missing sessions, or session file corruption problems.
When & Why to Use This Skill
The Claude Code Session Recovery skill is a specialized diagnostic and repair utility designed to resolve session management issues within the Claude Code CLI environment. It automates the troubleshooting of 'No conversations found' errors, identifies misconfigured environment variables (such as $HOME), and facilitates the recovery or migration of legacy session files to ensure persistent and reliable conversation history for developers.
Use Cases
- Resolving 'No conversations found to resume' errors when running the `claude -r` command.
- Diagnosing and correcting session storage discrepancies where files are incorrectly saved to /tmp/ instead of the standard ~/.claude/projects/ directory.
- Automating the recovery and migration of large volumes (600+) of legacy session files after environment changes or updates.
- Fixing session visibility issues caused by incorrect $HOME environment variable settings in IDEs or terminal emulators.
| name | session-recovery |
|---|---|
| description | Troubleshoot Claude Code session issues. Use when encountering "No conversations found" errors, missing sessions, or session file corruption problems. |
| allowed-tools | Read, Bash |
Claude Code Session Recovery Skill
Quick Reference
When to use this skill:
- "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
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 -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_EOF
Reference Documentation
For detailed diagnostic steps and solutions, see:
- Troubleshooting Guide - Detailed diagnostic procedures and fixes