Cross-Machine Sync
Understand how claude-sync resolves different paths across machines.
The Path Problem
Claude Code stores sessions at ~/.claude/projects/{encoded-path}/, where the encoded path is derived from your project's absolute filesystem path. If you work on /Users/john/app on your Mac and /home/john/app on your Linux machine, Claude sees these as two entirely different projects. claude-sync solves this with intelligent path encoding and symlink management.
Path Encoding
claude-sync uses a consistent path encoding scheme to identify projects across machines:
/Users/john/app → -Users-john-app /home/john/app → -home-john-app C:\Users\john\app → C-Users-john-app /Users/john/my projects/app → -Users-john-my-projects-app
Each directory separator is replaced with a dash, and the path is normalized. This encoding is consistent across platforms, enabling the CLI to map remote projects to local directories.
First-Run Flow
The first time you sync in a project directory, claude-sync detects if other devices have already synced and presents an interactive flow:
Detect Other Devices
The CLI checks if you have other registered devices with existing projects. If so, it prompts you to either push your local sessions as a new project or pull from an existing device.
Choose Action
You're presented with two options: Push as new project (upload your local sessions to the cloud) or Pull from another device (download sessions from a different machine).
Select Device & Project
If you choose to pull, the CLI lists all your devices and their projects. Select the source device, then choose which project to sync from.
Symlink Creation
The CLI downloads the remote sessions to ~/.claude/projects/{remote-encoded-path}/ and creates a symlink at ~/.claude/projects/{local-encoded-path}/ pointing to the remote directory. Future syncs work transparently through this symlink.
Symlink Strategy
claude-sync maintains bidirectional symlinks to handle cross-machine path differences:
# On MacBook Pro (/Users/john/app) ~/.claude/projects/-Users-john-app/ → (real directory with sessions) # On Linux Desktop (/home/john/app) ~/.claude/projects/-home-john-app/ → (symlink to -Users-john-app) ~/.claude/projects/-Users-john-app/ → (real directory downloaded from Mac)
When Claude Code runs on your Linux machine and looks for sessions in -home-john-app, it transparently follows the symlink to -Users-john-app, where the actual synced sessions live.
Project Links
claude-sync persists the mapping between local paths, remote paths, and source devices in ~/.claude-sync/project-links/*.json:
{
"localPath": "/home/john/app",
"localEncoded": "-home-john-app",
"remotePath": "/Users/john/app",
"remoteEncoded": "-Users-john-app",
"sourceDevice": "MacBook Pro",
"sourceDeviceId": "d8f3a2b1-7c4e-4a9f-b5d1-3e8f6a2c9d04",
"createdAt": "2026-02-05T10:23:11.000Z"
}This metadata allows the CLI to reconstruct symlinks if they're accidentally deleted and to show you which device a project originally came from.