[FEATURE REQUEST] Ability to move directories and not break --continue

[gwpl]

[docs/feature] claude --continue after moving directory : Guide + Internals explained

As I haven't found good claude feature or info in documentation how to proceed when moving project directory so claude --continue still works,

I run claude code to investigate claude code a bit, and produced clear instructions + explanation of internals how information about project history is stored,

that you may find useful either for updating docs, docs sdk or implementing directory ``claude mv` kind of feature... as I haven't found branch or repo to make merge request into documentation directly let me share here with community:

https://gist.github.com/gwpl/e0b78a711b4a6b2fc4b594c9b9fa2c4c

copy&paste in comment below: ...

[gwpl]

https://gist.github.com/gwpl/e0b78a711b4a6b2fc4b594c9b9fa2c4c

copy&paste in comment below

---

Claude Code Continue Functionality: Directory Migration Guide ( Claude Code --continue after Directory mv move - Migration Guide and Internal Mechanics explanation )

This guide explains how to preserve Claude Code's --continue functionality when moving project directories, along with the underlying mechanics.

Note: Claude Code currently lacks built-in directory migration features. Each directory maintains independent conversation sessions, and history doesn't automatically transfer when projects are moved.

Quick Fix: Steps to Maintain Continue History

When you move a project directory and want to preserve your conversation history:

1. Identify the Old and New Encoded Paths

Claude encodes directory paths by replacing forward slashes with hyphens:

# Original path
/home/user/projects/myapp

# Encoded path
-home-user-projects-myapp

2. Locate Your History Directory

Your conversation history is stored in:

~/.claude/projects/[encoded-directory-path]/

3. Rename the History Directory

After moving your project, rename the history directory to match:

# If you moved from:
/home/user/old-location/project
# To:
/home/user/new-location/project

# Run:
cd ~/.claude/projects/
mv -- -home-user-old-location-project -home-user-new-location-project

# Note: Use -- to prevent mv from interpreting the hyphen as an option

4. Verify

Navigate to your new project directory and run:

claude --continue

Your conversation history should be restored.

Alternative Approaches

Symbolic Links for History Preservation

If you frequently move directories, create a symbolic link:

# Create a stable location
mkdir -p ~/.claude/projects/stable-links
ln -s ~/.claude/projects/-actual-encoded-path ~/.claude/projects/stable-links/myproject

# When moving, just update the symlink
ln -sfn ~/.claude/projects/-new-encoded-path ~/.claude/projects/stable-links/myproject

Git Worktrees for Parallel Sessions

For maintaining separate conversation contexts on the same codebase:

# From your original repository
cd ~/path/foo
git worktree add ~/path/bar feature-branch

# Each worktree maintains independent Claude sessions
cd ~/path/bar && claude

This provides the cleanest separation while avoiding shared conversation state complexity.

How Claude's Continue System Works

Storage Architecture

Claude CLI uses a file-based storage system with the following structure:

~/.claude/
├── projects/
│   └── [encoded-directory-paths]/
│       ├── [session-uuid].jsonl     # Full conversation history
│       └── [summary-uuid].jsonl     # Conversation summaries
├── settings.json                     # Global user preferences
├── .credentials.json                 # Authentication
└── statsig/                         # Analytics and session tracking

Project-specific files (in your project directory):

project-root/
├── .claude/
│   ├── settings.json                 # Project settings
│   ├── settings.local.json          # Local overrides (gitignored)
│   └── commands/                    # Custom commands
├── CLAUDE.md                        # Project memory/context
└── .mcp.json                       # MCP server configuration

Session Files (JSONL Format)

Each conversation is stored in JSONL (JSON Lines) format, where each line represents a single event:

{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2025-06-02T18:46:59.937Z"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]},"timestamp":"2025-06-02T18:47:06.267Z"}

Each session file includes:

• parentUuid: Links messages in conversation threads
• sessionId: Unique identifier for the conversation session
• cwd: Working directory at message time
• version: Claude Code version
• timestamp: ISO 8601 timestamp

Directory Path Encoding

The encoding algorithm:

1. Take the absolute path of your working directory
2. Replace all / characters with -
3. This becomes the directory name under ~/.claude/projects/

Example transformations:

• /home/alice/code/project → -home-alice-code-project
• /Users/bob/Documents/work → -Users-bob-Documents-work
• /var/www/app → -var-www-app

Continue Resolution Process

When you run claude --continue:

1. Get Current Directory: Claude reads your current working directory (pwd)
2. Encode Path: Transforms the path using the encoding rules
3. Find History: Looks for ~/.claude/projects/[encoded-path]/
4. Load Sessions: Reads all JSONL files in that directory
5. Resume: Reconstructs the conversation state from the most recent session

Session Management Commands

• claude --continue: Resumes the most recent conversation in current directory
• claude --resume: Shows picker to select from previous sessions
• claude --continue --print "prompt": Continues with specific prompt
• /compact: Compresses conversation history to save context window

Headless automation:

claude -p "continue our previous work" --output-format stream-json

File Types

1. Session Files ([uuid].jsonl):

   • Contains complete message history
   • Includes tool uses and results
   • Preserves exact conversation flow

2. Summary Files ([uuid].jsonl):

   • Contains conversation summaries
   • Used for context when sessions get long
   • Helps with continuation across multiple sessions

Complete Migration Procedure

Step 1: Migrate Configuration Files

After moving from ~/path/foo to ~/path/bar, copy all Claude-specific files:

# Copy project-specific Claude files
cp -r ~/path/foo/.claude ~/path/bar/
cp ~/path/foo/CLAUDE.md ~/path/bar/
cp ~/path/foo/.mcp.json ~/path/bar/

# Update absolute paths in configuration files
sed -i 's|/path/foo|/path/bar|g' ~/path/bar/.claude/settings.json
sed -i 's|/path/foo|/path/bar|g' ~/path/bar/.mcp.json

Step 2: Migrate Conversation History

# Calculate encoded paths
OLD_ENCODED=$(echo "/path/foo" | sed 's/\//-/g')
NEW_ENCODED=$(echo "/path/bar" | sed 's/\//-/g')

# Move history directory
mv ~/.claude/projects/$OLD_ENCODED ~/.claude/projects/$NEW_ENCODED

Best Practices

1. Before Moving Directories

# Check your current encoded path
pwd | sed 's/\//-/g'

# List your existing Claude history
ls ~/.claude/projects/

2. Use Version Control for History

# Back up your Claude history
cd ~/.claude/projects/
git init
git add .
git commit -m "Backup Claude conversation history"

3. Clean Up Old Histories

# Remove histories older than 30 days
find ~/.claude/projects/ -type f -name "*.jsonl" -mtime +30 -delete

# Remove empty project directories
find ~/.claude/projects/ -type d -empty -delete

4. Project-Specific Instructions

Claude reads CLAUDE.md files in your project root for additional context. These move with your project automatically.

5. Automate Migration

Create a migration script:

#!/bin/bash
# claude-migrate.sh
OLD_PATH="$1"
NEW_PATH="$2"

# Encode paths
OLD_ENCODED=$(echo "$OLD_PATH" | sed 's/\//-/g')
NEW_ENCODED=$(echo "$NEW_PATH" | sed 's/\//-/g')

# Move history
if [ -d "$HOME/.claude/projects/$OLD_ENCODED" ]; then
    mv "$HOME/.claude/projects/$OLD_ENCODED" "$HOME/.claude/projects/$NEW_ENCODED"
    echo "Migrated conversation history"
fi

# Copy configuration
for file in .claude CLAUDE.md .mcp.json; do
    if [ -e "$OLD_PATH/$file" ]; then
        cp -r "$OLD_PATH/$file" "$NEW_PATH/"
    fi
done

Troubleshooting

Continue Not Finding History

1. Verify the encoded path matches:

   echo "Current encoded: $(pwd | sed 's/\//-/g')"
   ls ~/.claude/projects/ | grep "$(basename $(pwd))"

2. Check for multiple similar directories:

   ls ~/.claude/projects/ | grep -i "$(basename $(pwd))"

Permission Issues

Ensure proper permissions:

chmod -R 700 ~/.claude/

Corrupted History

If history appears corrupted:

1. Back up the directory
2. Validate JSONL files:

   for file in ~/.claude/projects/*/**.jsonl; do
     jq empty "$file" 2>/dev/null || echo "Invalid: $file"
   done

Current Limitations

The Claude Code community has actively requested better session persistence features. Current limitations:

• No automatic session migration between directories
• Each directory maintains completely independent conversation history
• No built-in export/import functionality for conversations
• Manual configuration transfer required when moving projects
• No cross-directory continuation support

Security Considerations

• History files may contain sensitive information
• Set appropriate permissions (700) on ~/.claude/ directory
• Consider encrypting ~/.claude/ if working with sensitive data
• Exclude ~/.claude/ from backups if necessary
• JSONL files contain full conversation content including code snippets

Advanced Tips

Debugging Path Encoding

# View all Claude project histories
ls -la ~/.claude/projects/ | grep "^d"

# Find history for current directory
CURRENT_ENCODED=$(pwd | sed 's/\//-/g')
ls -la ~/.claude/projects/$CURRENT_ENCODED/

# Check latest session
ls -t ~/.claude/projects/$CURRENT_ENCODED/*.jsonl | head -1 | xargs tail -1 | jq

Session File Analysis

# Count messages in a session
wc -l ~/.claude/projects/$CURRENT_ENCODED/*.jsonl

# Extract all user messages
grep '"type":"user"' ~/.claude/projects/$CURRENT_ENCODED/*.jsonl | jq -r '.message.content'

# Find sessions by date
find ~/.claude/projects/ -name "*.jsonl" -newermt "2025-06-01" -ls

Further Reading

• Claude Code Documentation: https://docs.anthropic.com/en/docs/claude-code
• JSONL Format: https://jsonlines.org/
• Unix File Permissions: https://en.wikipedia.org/wiki/File-system_permissions
• Community Feature Requests: GitHub Issues for claude-code

[hesreallyhim]

Thanks for sharing this

[hesreallyhim]

I haven't had time to peruse this, which is really detailed, thanks again, but I'd like to add one problem to the list:

• Deleting a directory does not delete the CC history for that directory.
  Repro:
• Start a session in a directory (".../foo"), have a chat.
• Close the session, rm -rf the directory, go have some coffee.
• Create a new directory with the same name as previous ("...foo")
• I think you can resume a session from the previously deleted directory. Also if you had a CLAUDE.md in the previous directory, I think might remember the instructions (since it reads them into the conversation at the beginning).

Sorry, I can't repro this right now, cuz API is having an outage, but I'm pretty sure deleting a directory does not delete the CC project folder.

[ogt]

Very useful!

[gitmpr]

In the path encoding of project names under ~/.claude/projects/

not only slashes, but also
dots in dir names area also replaced by hyphens it seems

~/git/github.com/claudia -> -home-USERNAME-git-github-com-claudia

unfortunately it seems claude wasn't able to find this out about itself

[dlond]

Hey folks! 👋

I built a tool to solve this problem: claude-cp

It copies Claude Code conversations between directories with an interactive picker. Perfect for the git worktree use case mentioned here.

Quick example:

# Copy a conversation to a new directory
claude-cp ~/my-new-feature

# Works even if source directory is deleted!
claude-cp ~/new-project ~/worktrees/deleted-branch

Features:

• 📋 Interactive fzf picker with conversation summaries and previews
• 🕐 Sorts by modification time (most recent first)
• 👻 Works with deleted source directories
• 🔗 Handles symlinks correctly (important for macOS /tmp → /private/tmp)
• 📁 Auto-creates destination directories
• --no-fzf fallback for non-interactive contexts

Repo: https://github.com/dlond/claude-tools

It uses the same ~/.claude/projects/ structure mentioned in the gist, but automates the whole process with a nice UX.

Would love feedback! Built entirely with Claude Code itself 🤖

[dlond]

claude-tools binaries for aarm64-darwin, and linux and mac nix users should be able to build locally

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.