Rescuing Your Claude Conversations When You Rename Projects

The Moment Everything Disappeared

You know that sinking feeling when you type /resume expecting to pick up where you left off, and Claude stares back with nothing?

That's what happens when you rename a project directory.

All those conversations about architectural decisions, debugging sessions, refactoring discussions—gone.

They're Not actually gone, they're just...lost in the void. They're orphaned in ~/.claude/ under your old directory name, which is now unreachable.

How Claude Remembers (And Forgets)

Claude Code's memory is actually brilliantly organized but it's absolutely rigid about directory paths. Everything lives in ~/.claude/ using encoded versions of your project paths:

• Sessions live in ~/.claude/projects/{encoded-path}/*.jsonl
• File edit history is in ~/.claude/file-history/{encoded-path}/
• Your todo lists is in ~/.claude/todos/{encoded-path}/
• Shell snapshots are in ~/.claude/shell-snapshots/{encoded-path}/
• The master index is in ~/.claude/history.jsonl mapping paths to sessions

The encoding is straightforward but strict: Claude replaces both / AND . with -. So /Users/you/projects/my-rad-project becomes -Users-you-projects-my-rad-project.

When you rename my-rad-project to my-awesome-project, Claude looks for -Users-you-projects-my-awesome-project and finds nothing. Your old sessions are still there under -Users-you-projects-my rad-project...which is totally useless to you as a user.

Enter claude-mv

I got tired of losing context every time I renamed something (company rebrands happen, project naming conventions evolve, projects merge). So I wrote a little script called claude-mv—a CLI tool that does what mv can't: safely migrate both your directory AND all its Claude context.

The magic is in the order of operations:

1. Conflict detection first - Checks if destination already has Claude context. If it does, it prompts to clean or merge
2. Move Claude context - Renames ~/.claude/projects/{old} → {new} BEFORE touching your directory
3. Rewrite session contents - Updates path references inside the .jsonl files themselves
4. Move the directory - Only now does it rename your actual project folder
5. Update the index - Patches ~/.claude/history.jsonl with new paths

That sequencing is critical. Context must move before the directory, otherwise the old paths don't exist to move from.

Why The Sequencing Matters

When I first attempted this, I made the obvious mistake: rename the directory first, then try to move Claude's files, which doesn't work.

Claude's context files reference the directory path they're associated with.

If you move the directory first, you're trying to move context from a path that no longer exists.

It's like trying to forward your mail after you've already moved out and you've lost your old address. The post office needs your old address to still exist when you file the change-of-address form.

The Merge Problem

Here's where it gets interesting: what if you've already started working in the destination directory? Maybe you renamed the folder manually weeks ago and have been building new context there. Now you want to reclaim your old sessions.

claude-mv detects this and offers two strategies:

• Clean: Delete the destination's context, replace with source (useful for fresh starts)
• Merge: Combine sessions from both locations (useful when you've worked on related stuff separately)

The merge is surprisingly handy. I've used it when working on the same project under different company names, or when prototyping in one directory and productionizing in another.

What This Actually Saves

Without this tool, renaming means starting fresh. You lose any conversation you've had since the beginning of working with this directory.

With claude-mv, you just run:

claude-mv ~/projects/old-name ~/projects/new-name

Everything comes with you. Resume your conversations like nothing happened.

Disaster Recovery

The best part? It works for accidental renames too.

If you already renamed a directory and lost your context, just run claude-mv to migrate it retroactively.

The tool doesn't care when the rename happened, only that it needs to reconcile the paths.

If you do a careless rename in Finder, no problem, you can easily recover everything.

Go Forth and Rename Fearlessly

The script lives in my dotfiles if you want to grab it. It's bash, it's commented, it does one thing well.

To use it, put it somewhere in your PATH. If you don't have a scripts directory set up yet, here's a clean approach:

# Create a dotfiles directory with scripts
mkdir -p ~/dotfiles/scripts
# Download the script
curl -o ~/dotfiles/scripts/claude-mv https://raw.githubusercontent.com/curiouslychase/dotfiles/main/scripts/claude-mv
# Make it executable
chmod +x ~/dotfiles/scripts/claude-mv

Then add this to your ~/.zshrc or ~/.bashrc:

export PATH="$HOME/dotfiles/scripts:$PATH"

Restart your shell (or run source ~/.zshrc), and you're set.

Rename your projects as often as you need. Your conversations will follow.