mcpField
S
session-recovery

session-recovery

github.com/terrylicaAgent 工作流2134 次安装1 天前更新
代码仓库

关于 session-recovery

用于诊断和恢复 Claude Code 会话历史的技能，重点处理会话存储路径、HOME 配置及旧会话迁移问题。

主要功能

  1. 01诊断会话存储位置问题
  2. 02检查 HOME 相关配置
  3. 03排查会话缺失或位置错误
  4. 04提供旧会话迁移指引

适用场景

  1. 01调查 claude -r 找不到会话的原因
  2. 02定位写入意外目录的会话
  3. 03环境变更后恢复会话历史可见性

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/terrylica/cc-skills --skill session-recovery

安装后在 Claude Code 中输入/session-recovery确认已加载。

附带文件references/evolution-log.mdTROUBLESHOOTING.md

详细介绍

Claude Code 会话恢复技能

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移或需要变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

  • 运行 claude -r 时出现“No conversations found to resume”
  • 新会话未创建会话文件
  • 会话出现在错误的位置（/tmp/ 而非 ~/.claude/projects/）
  • 环境变更后会话历史记录缺失
  • IDE/终端设置影响会话创建
  • 需要迁移或恢复 600 多个旧会话

快速参考

官方会话存储位置

标准位置： ~/.claude/projects/

结构：

~/.claude/projects/
├── -home-username-my-project/     # Encoded absolute path
│   └── 364695f1-13e7-4cbb-ad4b-0eb416feb95d.jsonl
└── -tmp-another-project/
    └── a8e39846-ceca-421d-b4bd-3ba0eb1b3145.jsonl

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

重要注意事项：HOME 变量

问题

Claude Code 使用 $HOME 环境变量来确定会话存储位置。如果 $HOME 不正确，会话就会保存到错误的目录，或者消失。

症状
  • claude -r 显示“No conversations found to resume”
  • 新会话可以正常运行，但预期位置没有出现文件
  • 在 /tmp/ 或其他意外路径中找到会话
  • 在一台机器上正常，在另一台机器上却不正常
诊断
/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

参考文档

如需详细的诊断步骤和解决方案，请参阅：

故障排除

问题原因解决方案
“No conversations found”HOME 变量错误确认 $HOME 与预期的用户目录一致
会话位于 /tmp/HOME 设置不正确修正 shell 配置文件中的 HOME，然后重启终端
会话文件缺失磁盘空间或权限问题检查 ~/.claude/projects/ 的权限和磁盘空间
显示了错误项目的会话路径编码不匹配检查编码后的路径是否与当前工作目录一致
会话未持久化文件系统问题确认对 ~/.claude/projects/ 具有写入权限
IDE 会话彼此独立不同环境使用了不同的 HOME确保终端和 IDE 使用一致的 HOME
看不到旧会话未完成迁移参阅 TROUBLESHOOTING.md 中的迁移部分
UUID 文件名损坏写入不完整检查是否存在部分写入的 .jsonl 文件，并删除损坏的文件

执行后复盘

此技能执行完成后，在结束前检查：

  1. 命令是否成功？ — 如果没有，请修复导致失败的说明或错误表格。
  2. 参数或输出是否发生变化？ — 如果底层工具的接口发生了变化，请更新用法示例和参数表，使其保持一致。
  3. 是否需要变通方案？ — 如果你不得不临时采用变通方法（不同的标志、额外步骤），请更新此 SKILL.md，避免下次调用时还需要同样的变通方法。

仅在问题真实且可复现时进行更新，不要基于推测进行更新。

评论

支持 Markdown