If you use Claude Code (Anthropic's official CLI), you've probably experienced this frustration:
You're deep into a coding session on your work laptop. Claude remembers your project context, your preferences, your conversation history. Everything is flowing perfectly.
Then you switch to your personal MacBook... and it's all gone.
Claude doesn't know what you were working on. Your custom agents? Gone. Your project memory? Vanished. You have to start from scratch.
I built Claude Sync to fix this.
What is Claude Sync?
Claude Sync is an open-source CLI tool that synchronizes your ~/.claude directory across devices using encrypted cloud storage.
Key Features:
- 🔐 End-to-end encryption - Files encrypted with age before upload
- 🔑 Passphrase-based keys - Same passphrase = same key on any device
- ☁️ Multi-cloud support - Cloudflare R2, AWS S3, or Google Cloud Storage
- 🆓 Free tier friendly - Works within free storage limits
- ⚡ Simple CLI - Just
pushandpull
# That's literally it
claude-sync push # Upload changes
claude-sync pull # Download changes
What Gets Synced?
Everything Claude Code stores locally:
| What | Why It Matters |
|---|---|
projects/ |
Session files, auto-memory for each project |
history.jsonl |
Your command history |
agents/ |
Custom agents you've created |
skills/ |
Custom skills |
plugins/ |
Installed plugins |
rules/ |
Custom rules |
settings.json |
Your preferences |
CLAUDE.md |
Global instructions for Claude |
Quick Start Guide
Install Claude Sync
Choose your preferred method:
# npm (recommended - works everywhere)
npm install -g @tawandotorg/claude-sync
# Or use npx for one-time use
npx @tawandotorg/claude-sync init
Daily Workflow
Once set up, your workflow is simple:
# Start of day (or when switching devices)
claude-sync pull
# ... use Claude Code normally ...
# End of day (or before switching devices)
claude-sync push
Pro Tip: Automate It
Add to your ~/.zshrc or ~/.bashrc:
# Auto-pull on shell start
if command -v claude-sync &> /dev/null; then
claude-sync pull -q &
fi
# Auto-push on shell exit
trap 'claude-sync push -q' EXIT
Get Started
npm install -g @tawandotorg/claude-sync
claude-sync init
claude-sync push
GitHub: github.com/tawanorg/claude-sync
Documentation: tawanorg.github.io/claude-sync
Feedback Welcome!
This is an open-source project. If you:
- Find bugs 🐛
- Have feature ideas 💡
- Want to contribute 🤝
Open an issue or PR on GitHub!
Have you struggled with syncing Claude Code across devices? What solutions have you tried? Let me know in the comments!
Top comments (2)
Hey, nice idea and clean execution! I was genuinely excited reading through this — the push/pull workflow is elegant.
But I have one concern that I think is pretty critical. Claude Code stores project sessions under ~/.claude/projects/, and from what I understand, it indexes them by the project's file-system path. So if I have a project at /Users/me/Downloads/my-app on machine1 and /Users/me/Documents/my-app on machine2, Claude Code would treat those as two completely separate projects internally.
That means even after syncing,
claude --resumeorclaude --continuefor a specific project won't actually pick up where I left off on the other machine — because the paths don't match. And continuing project sessions across devices was kind of the main selling point of the article, right?The global stuff that does sync — CLAUDE.md, settings.json, agents, skills, rules — those are definitely useful to have everywhere. But honestly, those can be synced pretty easily with a simple Git repo or even a dotfiles setup. No encryption or cloud bucket needed.
So my question is: does the tool handle path remapping somehow, or is this a known limitation? Because if project session continuity doesn't work across different paths, the core use case feels significantly weaker.
Not trying to be negative — the encryption approach with age + passphrase-derived keys is genuinely well thought out. Just think this path issue deserves some attention if the tool is going to deliver on its promise. Would love to hear your thoughts!
Thank you for your questions, and you raised an excellent point.
The tool does sync ~/.claude/projects/, but there's no path remapping logic. Claude Code indexes project sessions by absolute
filesystem path, so:
These are treated as completely different projects. After syncing, claude --resume on machine2 won't find the session from machine1
because it looks for a different path.
the core "continue sessions across devices" use case is significantly limited by
Claude Code's path-based indexing. I normally use same Consistent Path Structure .
I can find workaround for the next release maybe create symlinks to unify paths. thanks!