playbooks

home / skills / terrylica / cc-skills / session-recovery

session-recovery skill

/plugins/devops-tools/skills/session-recovery

This skill helps you recover Claude Code sessions by diagnosing HOME issues, locating session files, and guiding fixes across environments.

npx playbooks add skill terrylica/cc-skills --skill session-recovery

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
3.2 KB
---
name: session-recovery
description: Troubleshoot Claude Code session issues. TRIGGERS - No conversations found, missing sessions, session corruption.
allowed-tools: Read, Bash
---

# Claude Code Session Recovery Skill

## 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

```bash
/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](./TROUBLESHOOTING.md) - 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  |

Overview

This skill troubleshoots Claude Code session issues and restores lost or mislocated conversation histories. It targets cases where sessions are missing, written to unexpected locations, or corrupted, and guides you through diagnosis and recovery. The goal is to get Claude Code reading and writing sessions reliably across terminals, IDEs, and machines.

How this skill works

The skill inspects the runtime environment and filesystem to locate session JSONL files, verifies the HOME setting and path encodings, and identifies permission or disk problems. It provides concrete diagnostic checks and corrective steps to migrate, repair, or relocate session files so Claude Code can resume conversations. It flags partial or corrupt JSONL writes and suggests removal or repair strategies.

When to use it

  • "No conversations found to resume" appears when running session resume commands
  • New conversations are created but no session files appear in the expected directory
  • Session files are being written to /tmp or other unexpected paths
  • Session history disappears after OS, container, or IDE environment changes
  • You need to migrate hundreds of legacy sessions to the official storage layout

Best practices

  • Ensure $HOME matches the system user home directory in all environments (terminal, IDE, CI)
  • Keep sessions in the standard projects directory and avoid custom HOME overrides
  • Verify write permissions and available disk space for the sessions directory
  • Check for partial .jsonl files and remove or recover corrupted entries safely
  • Standardize environment configuration across shells, editors, and automation

Example use cases

  • Diagnose why claude resume shows no conversations after switching terminals
  • Locate sessions accidentally written to /tmp and move them to the projects folder
  • Repair or remove partially written JSONL files that break session loading
  • Migrate a large set of legacy session files into the encoded project layout
  • Ensure CI or containerized runs write session files to a persistent path

FAQ

Why do sessions appear in /tmp instead of my home directory?

Most often $HOME is set incorrectly for the process or environment. Verify the effective HOME for your shell or IDE and correct it so session writes target the expected projects directory.

How do I tell if a session file is corrupted?

Corrupted sessions often appear as incomplete JSONL files or fail JSON parsing. Inspect files for truncated lines or invalid JSON and remove or recover them from backups before retrying resume.