project-migration

Path Encoding Rules

BAD - Naive path encoding (breaks on spaces, drives, symlinks):

encoded = path.replace("/", "-").replace("\\", "-")
# C:\My Projects\app → C:-My Projects-app (WRONG: space, colon)

GOOD - Handle all edge cases:

path = str(Path(path).resolve())          # Resolve symlinks
path = path.replace('\\', '-').replace('/', '-')
if len(path) > 1 and path[1] == ':':     # Windows drive letter
    path = path[0].lower() + '-' + path[2:]
path = path.lstrip('-').replace(' ', '-') # Normalize
# C:\My Projects\app → c--My-Projects-app (CORRECT)

BAD - Migration with no rollback:

shutil.move(source, dest)  # If anything fails after this, data is split
rename_claude_data(old, new)
update_history(old, new)

GOOD - Migration with rollback on failure:

try:
    shutil.move(source, dest)
    rename_claude_data(old_key, new_key)
    update_history(old_path, new_path)
except Exception as e:
    # Rollback: move project back
    if dest.exists() and not source.exists():
        shutil.move(dest, source)
    if new_data.exists() and not old_data.exists():
        new_data.rename(old_data)
    raise RuntimeError(f"Migration failed, rolled back: {e}")

Claude Code encodes project paths as directory names in ~/.claude/projects/:

# Example transformations
# C:\Users\User\Desktop\myproject → C--Users-User-Desktop-myproject
# /home/user/dev/app → home-user-dev-app
# C:\Code\my app → C--Code-my-app

def encode_path(path: str) -> str:
    """Encode filesystem path to Claude directory name."""
    # Windows: C:\foo\bar → c--foo-bar
    # Unix: /foo/bar → foo-bar

    path = str(Path(path).resolve())  # Normalize

    # Replace separators
    path = path.replace('\\', '-').replace('/', '-')

    # Handle drive letter (Windows)
    if len(path) > 1 and path[1] == ':':
        path = path[0].lower() + '-' + path[2:]

    # Remove leading separator
    path = path.lstrip('-')

    # Replace spaces and underscores
    path = path.replace(' ', '-').replace('_', '-')

    return path

# Test examples
assert encode_path("C:\\Users\\Dev\\Desktop\\foo") == "c--Users-Dev-Desktop-foo"
assert encode_path("/home/user/projects/bar") == "home-user-projects-bar"
assert encode_path("C:\\Code\\my app") == "c--Code-my-app"