Skip to main content
skill CX Codex

session-recovery — Claude Code skill: what it does, how to install

session-recovery troubleshoots missing Claude Code sessions when claude -r reports no conversations found or files save to incorrect paths.

MIT 135 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill session-recovery -a claude-code
Open on GitHub

What session-recovery does

Claude Code records conversation logs as JSONL files in ~/.claude/projects/, encoding the absolute path of each project into folder names. When the $HOME environment variable differs between your IDE and terminal shell, session files often land in /tmp/ or drop out of resume menus entirely.

This skill runs preflight Bash commands to check active $HOME values against the system account database and searches the disk for displaced .jsonl files. It checks write permissions for project directories and identifies corrupted UUID log files created during incomplete write cycles.

Executing these diagnosis scripts requires access to both Read and Bash tools.

What it helps with

  • diagnose 'No conversations found to resume' errors in claude -r
  • locate misplaced JSONL session logs dumped into /tmp/
  • resolve session path mismatches caused by inconsistent HOME variables
  • clean up corrupt UUID session records caused by interrupted writes

Example prompts for the agent

  • Help me locate my Claude Code session files after claude -r failed to find them
  • Check why my Claude Code sessions are being written to /tmp/ instead of my home folder
  • Inspect ~/.claude/projects/ for corrupt JSONL files and fix my HOME path

How to install session-recovery

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill session-recovery -a claude-code

2Manually: put the files in place

~/.claude/skills/session-recovery/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/session-recovery/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about session-recovery

How to install session-recovery in Claude Code?

Run npx skills add terrylica/cc-skills --skill session-recovery -a claude-code. You can also place the file directly at ~/.claude/skills/session-recovery/SKILL.md.

What does the session-recovery skill do?

It diagnoses session loss in Claude Code by locating misplaced JSONL files, verifying $HOME consistency, and identifying damaged session files.

Which tools must be enabled for this skill?

The skill requires Bash and Read tools to inspect environment variables and verify project paths on the filesystem.

Source text

SKILL.md · MIT
---
name: session-recovery
description: "Diagnose and recover Claude Code session problems: 'No conversations found to resume', sessions in the wrong location, missing or corrupted session files."
allowed-tools: Read, Bash
---

# 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

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

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

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set79

The whole set →
slash-command-factory slash-command-factory generates Claude Code slash command Markdown files with YAML frontmatter through a question workflow or ten presets. CX Codex +1 136installs backtesting-py-oracle backtesting-py-oracle configures backtesting.py to match ClickHouse SQL sweep results on range bars. Fixes trade count mismatches and timing discrepancies in multi-position testing. CX Codex +1 135installs doppler-secret-validation The doppler-secret-validation skill helps store secrets in Doppler, verify retrieval, and test API authentication. Use it to check a token before relying on it in a project. CX Codex +1 135installs link-validation link-validation runs an offline lychee pass over a project's markdown and reports broken relative links, root-relative paths and anchors. Handy right before you commit docs. CX Codex +1 135installs session-chronicle session-chronicle connects findings, decisions, and code changes to session UUIDs. Use it when you need to trace where work came from or record session provenance. CX Codex +1 135installs notion-sdk notion-sdk — a skill for managing Notion via the official Python SDK. Creates pages and databases, queries information, adds content blocks — all programmatically. CX Codex +1 133installs hooks-development The hooks-development skill guides you through building and debugging Claude Code hooks, with a focus on output visibility. Use it when a hook runs but its message never reaches the agent. CX Codex +1 133installs asciinema-cast-format asciinema-cast-format is a Claude Code skill that helps parse NDJSON headers and terminal events in asciinema v3 .cast recordings. CX Codex +1 132installs

Project sponsors

Companies that keep this analytics open