session-recovery_skill

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

TypeScript

14

GitHub Stars

2

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

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

SKILL.md3.2 KB
TROUBLESHOOTING.md5.4 KB

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

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.