claude-sync

---

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)

1. Go to Cloudflare Dashboard → R2 Object Storage
2. Click "Create bucket" → name it claude-sync
3. Go to "Manage R2 API Tokens" → "Create API Token"
4. Select Object Read & Write permission → Create

You'll need: Account ID, Access Key ID, Secret Access Key

AWS S3

1. Go to S3 Console → Create bucket
2. Go to IAM Security Credentials
3. Create Access Keys

You'll need: Access Key ID, Secret Access Key, Region

Google Cloud Storage

1. Go to Cloud Storage → Create bucket
2. Go to Service Accounts → Create service account
3. 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:

1. Select storage provider (R2, S3, or GCS)
2. Enter credentials (provider-specific)
3. Choose encryption method:
   • Passphrase (recommended) - same passphrase on all devices = same key
   • Random key - must copy ~/.claude-sync/age-key.txt to other devices
4. 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: