Back to Details

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"
echo "Current HOME: $HOME"

Step 2: Check system expectation

步骤2：检查系统预期值

echo "Expected HOME: $(getent passwd $(whoami) | cut -d: -f6)"
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

故障排查

IssueCauseSolution
"No conversations found"Wrong HOME variableVerify 
$HOME
matches expected user directory
Sessions in /tmp/HOME set incorrectlyFix HOME in shell profile, restart terminal
Session files missingDisk space or permissionsCheck 
~/.claude/projects/
permissions and disk
Wrong project sessions shownPath encoding mismatchCheck encoded path matches current working directory
Sessions not persistingFile system issuesVerify write permissions to 
~/.claude/projects/
IDE sessions separateDifferent HOME per environmentEnsure consistent HOME across terminal and IDE
Legacy sessions not visibleMigration not completeSee migration section in TROUBLESHOOTING.md
UUID filename corruptionIncomplete writesCheck 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文件，删除损坏的文件