How to Move or Rename Claude Code Project Folders Without Losing Session History

The Problem: mv Breaks Claude Code Session History

Claude Code stores your session history in ~/.claude/projects/ using the exact absolute path of your project as an identifier. For example, a project at /Users/alex/my-project gets a session folder at: ~/.claude/projects/-Users-alex-my-project/.

When you use mv to move or rename a project folder, the path no longer matches and all your sessions become invisible to Claude Code. The data isn't deleted but becomes orphaned.

The Solution: clamp Tool

clamp is a community-built tool that handles folder renaming, moving, or both while preserving Claude Code session history.

Install via Homebrew:

brew install wsagency/tap/clamp

Steps to Use clamp

Follow these steps in order:

1. Dry run first (preview changes):
   clamp --dry-run /Users/alex/old-project-name /Users/alex/documents/new-project-name
   Check output for session files detected and new paths confirmed.
2. Run the real migration:
   clamp /Users/alex/old-project-name /Users/alex/documents/new-project-name
   Type y to confirm.
3. Verify everything landed correctly:
   clamp --list clamp --verify
4. Resume your session:
   cd /Users/alex/documents/new-project-name
claude --continue

If You Already Used mv

If you already moved the folder with mv and broke session access, use the --fix command:

clamp --fix --from /Users/alex/old-project-name --to /Users/alex/documents/new-project-name

This tool addresses a specific pain point for developers who reorganize their project structures while maintaining access to their Claude Code conversation history.