claude-sync

Sync your Claude Code setup across machines — memories, sessions, tasks, plans, skills, and settings.

Claude Code stores everything locally. Switch machines and you lose your project context, conversation history, and muscle memory. claude-sync fixes that by pushing everything to a backend of your choice and pulling it back on any other machine.

What gets synced

| What | Where it lives | |---|---| | Global settings | ~/.claude/settings.json | | Global instructions | ~/CLAUDE.md | | Project memory | ~/.claude/projects/*/memory/ | | Conversation history | ~/.claude/history.jsonl | | Sessions (for /resume) | ~/.claude/sessions/ + per-project .jsonl files | | Tasks | ~/.claude/tasks/ | | Plans | ~/.claude/plans/ | | Custom commands | ~/.claude/commands/ | | Skills | ~/.claude/skills/ | | Project settings | .claude/settings.json in your working directory | | Project CLAUDE.md | CLAUDE.md in your working directory |

Install

npm install -g claude-sync

Quick start

On your first machine:

claude-sync init   # choose a provider, name this machine
claude-sync push   # upload everything

On every other machine:

claude-sync init   # point at the same provider
claude-sync pull   # restore everything

That's it. Open Claude Code and /resume your last session.

Commands

claude-sync init     Set up claude-sync on this machine
claude-sync push     Upload local Claude files to your provider
claude-sync pull     Download and restore files from your provider
claude-sync edit     Change the provider or machine name
claude-sync remove   Disconnect this machine (remote files are not deleted)

Providers

GitHub (recommended for developers)

Uses a private GitHub repository. Every push is a commit, so you get a full history of your Claude state.

You'll need a personal access token with repo scope.

Provider:   github
Repo:       your-username/claude-sync-data
Branch:     main
Token:      stored at ~/.claude-sync/secrets.json (mode 600)

Files from multiple machines accumulate — pushing from machine A won't overwrite machine B's files.

Local folder

Point at any folder that's already synced by Dropbox, iCloud, OneDrive, or any other tool you trust.

Provider:   local
Path:       ~/Dropbox/claude-sync

No accounts, no APIs, no tokens. If the folder syncs, claude-sync works.

How paths work across machines

Claude Code stores project data using the full local path as a key (e.g. /Users/alice/dev/project becomes -Users-alice-dev-project). claude-sync strips the machine-specific home directory prefix before storing, so the same project syncs correctly regardless of username.

One requirement: the project must live at the same relative path from your home directory on both machines. ~/dev/project on machine A should be ~/dev/project on machine B.

Security

• Your GitHub token is stored in ~/.claude-sync/secrets.json with permissions 600 (owner read/write only)
• Alternatively, set CLAUDE_SYNC_GITHUB_TOKEN as an environment variable — the file is never written in that case
• For the local provider, security is whatever your sync tool provides
• claude-sync never sends data anywhere except the provider you configure

License

MIT