session-recovery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Session Recovery Skill

Claude Code 会话恢复 Skill

When to Use This Skill

何时使用此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

在以下场景中使用此Skill：

运行
```
claude -r
```
时提示“未找到可恢复的对话”
新建对话未生成会话文件
会话出现在错误位置（
```
/tmp/
```
而非
```
~/.claude/projects/
```
）
环境变更后会话历史丢失
IDE/终端设置影响会话创建
需要迁移或恢复600+个旧版会话

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

标准位置：

~/.claude/projects/

结构：

~/.claude/projects/
├── -home-username-my-project/     # 编码后的绝对路径
│   └── 364695f1-13e7-4cbb-ad4b-0eb416feb95d.jsonl
└── -tmp-another-project/
    └── a8e39846-ceca-421d-b4bd-3ba0eb1b3145.jsonl

格式： 每行一个JSON事件（JSONL），基于UUID的文件名

Critical Pitfall: HOME Variable

关键陷阱：HOME环境变量

Problem

问题

Claude Code uses

$HOME

environment variable to determine session storage location. If

$HOME

is incorrect, sessions go to wrong directory or disappear.

Claude Code 使用

$HOME

环境变量确定会话存储位置。如果

$HOME

设置错误，会话会被保存到错误目录或消失。

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

```
claude -r
```
显示“未找到可恢复的对话”
新建对话可正常使用，但文件未出现在预期位置
会话出现在
```
/tmp/
```
或其他意外路径
在一台机器上可用，另一台不可用

Diagnosis

诊断

bash

/usr/bin/env bash << 'PREFLIGHT_EOF'

bash

/usr/bin/env bash << 'PREFLIGHT_EOF'

Step 1: Check current HOME

步骤1：检查当前HOME

echo "Current HOME: $HOME"

Step 2: Check system expectation

步骤2：检查系统预期值

echo "Expected HOME: $(getent passwd $(whoami) | cut -d: -f6)"

Step 3: Find where Claude is actually writing

步骤3：查找Claude实际写入的位置

find /tmp -name ".jsonl" -path "/.claude/projects/*" 2>/dev/null PREFLIGHT_EOF

---

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

故障排查

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

问题	原因	解决方案
“未找到对话”	HOME变量错误	验证 `$HOME` 是否与预期用户目录匹配
会话存放在/tmp/中	HOME设置错误	在shell配置文件中修复HOME，重启终端
会话文件丢失	磁盘空间或权限问题	检查 `~/.claude/projects/` 的权限和磁盘空间
显示错误的项目会话	路径编码不匹配	检查编码路径是否与当前工作目录一致
会话无法持久化	文件系统问题	验证对 `~/.claude/projects/` 的写入权限
IDE会话独立分开	不同环境HOME不同	确保终端和IDE中的HOME一致
旧版会话不可见	迁移未完成	查看TROUBLESHOOTING.md中的迁移章节
UUID文件名损坏	写入不完整	检查是否存在不完整的.jsonl文件，删除损坏的文件