Back to Details

project-directory-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Directory Migration

项目目录迁移

Safely migrate Claude Code project context (sessions, memory, history) when renaming a project directory.
重命名项目目录时，安全迁移Claude Code项目上下文（会话、记忆、历史记录）。

When to Use This Skill

何时使用此技能

Use this skill when:
  • Renaming a project directory (e.g., 
    my-old-name/
    to 
    my-new-name/
    )
  • Moving a project to a different path
  • User says "No conversations found" after a directory rename
  • Reorganizing workspace directories
  • Package rename requires matching directory name to GitHub repo name
  • Recovering sessions that became orphaned after a directory move
在以下场景使用此技能：
  • 重命名项目目录（例如：
    my-old-name/
    改为 
    my-new-name/
    ）
  • 将项目移动到其他路径
  • 重命名目录后出现“未找到对话”提示
  • 重组工作区目录
  • 包重命名要求目录名称与GitHub仓库名称匹配
  • 恢复因目录移动而孤立的会话

Interactive Workflow

交互式工作流

Phase 1: Gather Facts

阶段1：收集信息

Use AskUserQuestion to collect source and target paths.
Question 1 (header: "Source"): "What is the current project directory path?"
  Options:
    - "Use current directory: $PWD" (Recommended)
    - "Specify a different path"

Question 2 (header: "Target"): "What should the new directory path be?"
  Options:
    - (User provides via "Other" free text)
使用AskUserQuestion收集源路径和目标路径。
问题1（标题："源路径"）："当前项目目录路径是什么？"
  选项：
    - "使用当前目录: $PWD"（推荐）
    - "指定其他路径"

问题2（标题："目标路径"）："新的目录路径应该是什么？"
  选项：
    - （用户通过“其他”自由文本输入）

Phase 2: Dry-Run Audit

阶段2：预演审计

Run the migration script in 
--dry-run
mode to discover what needs migrating:
bash
bash "<skill-scripts>/claude-code-migrate.sh" --dry-run "$OLD_PATH" "$NEW_PATH"
Present findings to user:
  • Number of session files found
  • Number of history.jsonl entries to rewrite
  • Whether auto-memory (MEMORY.md) exists
  • Environment tooling detected (mise, uv, direnv, asdf)
以
--dry-run
模式运行迁移脚本，查看需要迁移的内容：
bash
bash "<skill-scripts>/claude-code-migrate.sh" --dry-run "$OLD_PATH" "$NEW_PATH"
向用户展示结果：
  • 找到的会话文件数量
  • 需要重写的history.jsonl条目数量
  • 是否存在自动记忆（MEMORY.md）
  • 检测到的环境工具（mise、uv、direnv、asdf）

Phase 3: Scope and Confirm

阶段3：范围确认

Question 3 (header: "Scope", multiSelect: true):
  "What should be included in migration?"
  Options:
    - "Claude Code sessions + history (Recommended)"
    - "Auto-memory (MEMORY.md) (Recommended)"
    - "Backward-compatibility symlink (Recommended)"
    - "Auto-fix environment: mise trust, venv recreate (Recommended)"

Question 4 (header: "Execute"):
  "Ready to migrate? The script creates a timestamped backup first."
  Options:
    - "Execute migration now (Recommended)"
    - "Export copy-paste commands for manual execution"
    - "Cancel"
If user chooses "Export copy-paste commands": Generate the exact commands they can paste into their terminal after closing Claude Code. This is the safest option since Claude Code won't be accessing the project files during migration.
问题3（标题："迁移范围"，可多选）：
  "迁移应包含哪些内容？"
  选项：
    - "Claude Code会话 + 历史记录（推荐）"
    - "自动记忆（MEMORY.md）（推荐）"
    - "向后兼容符号链接（推荐）"
    - "自动修复环境：mise trust、venv重建（推荐）"

问题4（标题："执行操作"）：
  "准备好迁移了吗？脚本会先创建带时间戳的备份。"
  选项：
    - "立即执行迁移（推荐）"
    - "导出可复制粘贴的命令以手动执行"
    - "取消"
如果用户选择“导出可复制粘贴的命令”：生成用户关闭Claude Code后可粘贴到终端的精确命令。这是最安全的选项，因为迁移过程中Claude Code不会访问项目文件。

Phase 4: Post-Migration Report

阶段4：迁移后报告

After migration completes, report:
  • Sessions migrated, history entries rewritten
  • Environment fixups applied (mise trust, venv recreated)
  • Remaining manual steps (git remote update, etc.)
  • Rollback command if anything goes wrong
迁移完成后，报告以下内容：
  • 已迁移的会话、已重写的历史条目
  • 已应用的环境修复（mise trust、venv重建）
  • 剩余的手动步骤（如git远程更新等）
  • 出现问题时的回滚命令

Quick Reference

快速参考

Claude Code Path Encoding

Claude Code路径编码

Claude Code encodes directory paths by replacing 
/
with 
-
:
/Users/alice/projects/my-app  -->  -Users-alice-projects-my-app
Claude Code通过将
/
替换为
-
来编码目录路径：
/Users/alice/projects/my-app  -->  -Users-alice-projects-my-app

Storage Locations

存储位置

AssetLocation
Sessions
~/.claude/projects/{encoded-path}/*.jsonl
Memory
~/.claude/projects/{encoded-path}/memory/MEMORY.md
Session index
~/.claude/projects/{encoded-path}/sessions-index.json
History
~/.claude/history.jsonl
Subagents
~/.claude/projects/{encoded-path}/{session-id}/subagents/
资产存储位置
会话
~/.claude/projects/{encoded-path}/*.jsonl
记忆
~/.claude/projects/{encoded-path}/memory/MEMORY.md
会话索引
~/.claude/projects/{encoded-path}/sessions-index.json
历史记录
~/.claude/history.jsonl
子Agent
~/.claude/projects/{encoded-path}/{session-id}/subagents/

What Contains Path References

包含路径引用的文件

FileFields with pathsNeeds rewriting?
sessions-index.json
originalPath
, 
entries[].projectPath
, 
entries[].fullPath
Yes
history.jsonl
project
field per entry		Yes
Session 
.jsonl
files		NoneNo
MEMORY.md
None (content only)No
文件包含路径的字段是否需要重写？
sessions-index.json
originalPath
, 
entries[].projectPath
, 
entries[].fullPath
是
history.jsonl
每个条目的
project
字段		是
会话
.jsonl
文件		无否
MEMORY.md
无（仅内容）否

Migration Script

迁移脚本

Located at 
scripts/claude-code-migrate.sh
.
位于
scripts/claude-code-migrate.sh
。

Usage

使用方法

bash
undefined
bash
undefined

Dry run (preview what would happen)

预演（预览将执行的操作）

bash scripts/claude-code-migrate.sh --dry-run /old/path /new/path
bash scripts/claude-code-migrate.sh --dry-run /old/path /new/path

Execute migration

执行迁移

bash scripts/claude-code-migrate.sh /old/path /new/path
bash scripts/claude-code-migrate.sh /old/path /new/path

Rollback from most recent backup

从最近的备份回滚

bash scripts/claude-code-migrate.sh --rollback
bash scripts/claude-code-migrate.sh --rollback

Show help

显示帮助

bash scripts/claude-code-migrate.sh --help
undefined
bash scripts/claude-code-migrate.sh --help
undefined

9-Phase Execution

9阶段执行流程

  1. Pre-flight validation — 7 checks (paths, Claude Code dir, python3, no running sessions)
  2. Backup — Timestamped copy to 
    ~/.claude/migration-backup-YYYYMMDD-HHMMSS/
  3. Move project directory — Rename in 
    ~/.claude/projects/
  4. Rewrite sessions-index.json — Update projectPath, fullPath, originalPath
  5. Rewrite history.jsonl — Update project field (JSON-safe, preserves Unicode)
  6. Backward-compatibility symlink — Old encoded path symlinks to new
  7. Rename repo directory — 
    mv /old/path /new/path
  8. Environment fixups — mise trust, venv recreate, direnv/asdf warnings
  9. Post-flight verification — Sessions count, memory, symlink, env health
  1. 飞行前验证 — 7项检查（路径、Claude Code目录、python3、无运行中的会话）
  2. 备份 — 将内容复制到带时间戳的
    ~/.claude/migration-backup-YYYYMMDD-HHMMSS/
    目录
  3. 移动项目目录 — 在
    ~/.claude/projects/
    中重命名
  4. 重写sessions-index.json — 更新projectPath、fullPath、originalPath
  5. 重写history.jsonl — 更新project字段（支持JSON格式，保留Unicode）
  6. 创建向后兼容符号链接 — 旧编码路径链接到新路径
  7. 重命名仓库目录 — 
    mv /old/path /new/path
  8. 环境修复 — mise trust、venv重建、direnv/asdf提示
  9. 飞行后验证 — 会话数量、记忆、符号链接、环境健康状态

Reference Documentation

参考文档

  • Session Storage Anatomy — How Claude Code stores project data
  • Troubleshooting Guide — Common post-migration issues and fixes
  • Evolution Log — Skill improvement history
  • 会话存储结构 — Claude Code如何存储项目数据
  • 故障排除指南 — 常见迁移后问题及解决方法
  • 版本更新日志 — 技能改进历史

Troubleshooting

故障排除

IssueAuto-fixed?Manual Solution
mise trust error after renameYes (Phase 8)
mise trust <new-path>
(old-name)
in shell prompt		Yes (Phase 8)Restart terminal or 
uv sync
VIRTUAL_ENV path mismatchYes (Phase 8)
uv sync --dev
recreates venv
"No conversations found"Yes (Phase 4)Re-run migration script
.envrc
not allowed		Warned (Phase 8)
direnv allow
Git push auth failsNoUpdate credential helper or remote URL
Session subdirs missingNoUse 
--rollback
, retry
问题是否自动修复？手动解决方案
重命名后出现mise trust错误是（阶段8）
mise trust <new-path>
shell提示符中显示
(old-name)
是（阶段8）重启终端或执行
uv sync
VIRTUAL_ENV路径不匹配是（阶段8）
uv sync --dev
重建venv
“未找到对话”提示是（阶段4）重新运行迁移脚本
.envrc
未被允许		仅提示（阶段8）
direnv allow
Git推送认证失败否更新凭证助手或远程URL
会话子目录缺失否使用
--rollback
，重试