Features
- Cross-device sync: Continue Claude Code conversations on any laptop
- Multi-provider storage: Cloudflare R2, AWS S3, or Google Cloud Storage
- End-to-end encryption: All files encrypted with age before upload
- Passphrase-based keys: Same passphrase = same key on any device (no file copying)
- Interactive wizard: Arrow-key driven setup with validation
- Self-updating:
claude-sync update to get the latest version
- Simple CLI:
push, pull, status, diff, conflicts commands
- Compression: Gzip compression before encryption for faster syncs
- Auto-sync hooks: Optional Claude Code hooks for automatic push/pull
Quick Start
First Device
# Install
npm install -g @tawandotorg/claude-sync
# Set up (interactive wizard)
claude-sync init
# Push your sessions
claude-sync push
Second Device
# Install
npm install -g @tawandotorg/claude-sync
# Set up with SAME storage credentials
claude-sync init
# Select same provider (R2/S3/GCS)
# Enter same bucket name and credentials
# Choose "Passphrase" for encryption
# Enter the SAME passphrase as first device
# ✓ Encryption key verified <-- confirms passphrase matches!
# Preview what would be synced
claude-sync pull --dry-run
# Pull sessions (creates backup if you have existing files)
claude-sync pull
Same passphrase = same encryption key. The init verifies your passphrase can decrypt remote files before completing.
Setup Guide
Step 1: Choose a Storage Provider
| Provider | Free Tier | Best For |
|---|
| Cloudflare R2 | 10GB storage | Personal use (recommended) |
| AWS S3 | 5GB (12 months) | AWS users |
| Google Cloud Storage | 5GB | GCP users |
Step 2: Create a Bucket
Cloudflare R2 (recommended)
- Go to Cloudflare Dashboard → R2 Object Storage
- Click "Create bucket" → name it
claude-sync
- Go to "Manage R2 API Tokens" → "Create API Token"
- Select Object Read & Write permission → Create
You'll need: Account ID, Access Key ID, Secret Access Key
AWS S3
- Go to S3 Console → Create bucket
- Go to IAM Security Credentials
- Create Access Keys
You'll need: Access Key ID, Secret Access Key, Region
Google Cloud Storage
- Go to Cloud Storage → Create bucket
- Go to Service Accounts → Create service account
- Grant "Storage Object Admin" role → Create JSON key
You'll need: Project ID, Service Account JSON file (or use gcloud auth application-default login)
Step 3: Run Init
claude-sync init
The interactive wizard will guide you through:
- Select storage provider (R2, S3, or GCS)
- Enter credentials (provider-specific)
- Choose encryption method:
- Passphrase (recommended) - same passphrase on all devices = same key
- Random key - must copy
~/.claude-sync/age-key.txt to other devices
- Test the connection to verify everything works
Step 4: Push and Pull
# Upload local changes
claude-sync push
# Download remote changes
claude-sync pull
What Gets Synced
| Path | Content |
|---|
~/.claude/projects/ | Session files, auto-memory |
~/.claude/history.jsonl | Command history |
~/.claude/agents/ | Custom agents |
~/.claude/skills/ | Custom skills |
~/.claude/plugins/ | Plugins |
~/.claude/rules/ | Custom rules |
~/.claude/settings.json | Settings |
~/.claude/settings.local.json | Local settings |
~/.claude/CLAUDE.md | Global instructions |
Limitations
Path-Based Session Indexing
Claude Code indexes project sessions by absolute filesystem path. This tool syncs ~/.claude/projects/ but does not perform path remapping, which means:
