claude-sync

Encrypted with age • R2 / S3 / GCS / WebDAV supported

Quick Start • Setup Guide • Commands • Shell Integration • Security

---

Features

• Cross-device sync: Continue Claude Code conversations on any laptop
• Multi-provider storage: Cloudflare R2, AWS S3, Google Cloud Storage, S3-compatible (Backblaze B2, MinIO, Wasabi), or WebDAV (Nextcloud, ownCloud)
• End-to-end encryption: All files encrypted with age before upload
• Passphrase-based keys: Same passphrase = same key on any device (no file copying)
• Selective sync: Choose --scope sessions to sync only conversation data (skip plugins/node_modules)
• Interactive wizard: Arrow-key driven setup with validation
• Secure self-updating: claude-sync update downloads and verifies SHA256 checksums
• Simple CLI: push, pull, status, diff, conflicts commands
• Compression: Gzip compression before encryption for faster syncs
• Shell integration: Optional shell 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/WebDAV)
# 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
S3-compatible	varies	Backblaze B2, MinIO, Wasabi, DigitalOcean Spaces, self-hosted
WebDAV	Self-hosted (unlimited)	Nextcloud/ownCloud users

Step 2: Create a Bucket

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

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

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)

Any provider exposing an S3-compatible API works through the S3-compatible (custom endpoint) option. Create a bucket and an application key with your provider, then supply its S3 endpoint URL.

Example (Backblaze B2):

claude-sync init --provider s3-compatible --endpoint https://s3.us-west-004.backblazeb2.com

You'll need: Endpoint URL, Access Key ID, Secret Access Key, Bucket. The signing region is auto-detected from the endpoint (e.g. us-west-004); for providers that ignore it, auto is used.

For servers that don't resolve buckets as subdomains (e.g. Ceph RGW, or MinIO without wildcard DNS), add --use-path-style to address objects as endpoint/bucket/key instead of bucket.endpoint/key:

claude-sync init --provider s3-compatible --endpoint https://ceph.example.com --use-path-style

It's off by default and unnecessary for Backblaze B2, Wasabi, and DigitalOcean Spaces, which all support virtual-hosted addressing.

Custom endpoints automatically relax the AWS SDK's default integrity-checksum headers, which some S3-compatible providers reject. AWS S3 behavior is unchanged.

No bucket to create — just point at your existing WebDAV server.

1. Nextcloud: Go to Settings → Security → Devices & sessions → Create app password
2. Note your WebDAV URL: https://your-server/remote.php/dav/files/USERNAME/

You'll need: WebDAV URL, Username, App password

The wizard will create a claude-sync subdirectory automatically.

Step 3: Run Init

claude-sync init

The interactive wizard will guide you through:

1. Select storage provider (R2, S3, GCS, or WebDAV)
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/plans/	Implementation plans from plan mode
~/.claude/tasks/	Task tracking state
~/.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

Sync scope

init asks whether to sync everything or just conversation data; you can also set it with --scope:

Scope	Syncs	Use when
full (default)	everything in the table above	you want settings, skills, agents, and plugins mirrored too
sessions	projects/, history.jsonl, tasks/, plans/ only	you just want claude --resume to work across machines

claude-sync init --scope sessions

Why sessions exists: full includes plugins/, whose plugin caches bundle node_modules and Python .venv trees — thousands of large, machine-/arch-specific files that are regenerated on demand and should not be synced. sessions skips them, keeping syncs small, fast, and portable. The scope is saved in ~/.claude-sync/config.yaml and applies to every push/pull.

Cross-Device Path Mapping

Claude Code indexes project sessions by absolute filesystem path:

/Users/alice/my-app → ~/.claude/projects/-Users-alice-my-app/
/Users/bob/my-app   → ~/.claude/projects/-Users-bob-my-app/

Synced verbatim, those would be different projects and claude --resume on the second machine would never find the first machine's sessions. claude-sync solves this by translating paths during sync:

• Home directories are mapped automatically. Sessions are stored remotely under a portable ${HOME} token (in both remote keys and transcript content), then rewritten to each device's real home on pull. Different usernames across machines just work.

• Other layout differences are configurable. If one machine keeps projects in ~/work and another in ~/Projects, point both at the same token in ~/.claude-sync/config.yaml:

  # machine 1
  path_map:
    ~/work: WORK
  

  # machine 2
  path_map:
    ~/Projects: WORK
  

  Sessions under either directory sync to the shared ${WORK} namespace and resume correctly on both machines.

Upgrading from an older version? Run claude-sync migrate once on each device to convert existing remote data to portable keys. Paths the current device doesn't own are left for the other device's migrate run.

Commands

claude-sync init        # Set up configuration (interactive wizard)
claude-sync push        # Upload local changes to cloud storage
claude-sync pull        # Download remote changes from cloud storage
claude-sync status      # Show pending local changes
claude-sync diff        # Show differences between local and remote
claude-sync conflicts   # List and resolve conflicts
claude-sync rebuild-history  # Rebuild ~/.claude/history.jsonl from session files
claude-sync reset       # Reset configuration (forgot passphrase)
claude-sync migrate     # Convert legacy remote keys to portable path-mapped keys
claude-sync update      # Update to latest version (verifies release checksums)
claude-sync changelog   # Show release history
claude-sync --help      # Show all commands

Pull Options

claude-sync pull                    # Normal pull (prompts if existing files)
claude-sync pull --dry-run          # Preview what would change
claude-sync pull --force            # Skip confirmation prompts
claude-sync pull --rebuild-history  # Also rebuild history.jsonl after pulling

Rebuilding Prompt History

history.jsonl is synced as a single file, so pushes from two devices are last-writer-wins and one device's prompt-history entries can be lost — which breaks the /resume session picker. Session files sync cleanly (one file per session), so the history can always be reconstructed from them:

claude-sync rebuild-history         # One-off rebuild
claude-sync pull --rebuild-history  # Rebuild automatically after a pull

Every existing entry is preserved, recovered prompts are merged in and sorted by timestamp, and the previous file is kept as history.jsonl.bak.

Init Options

claude-sync init              # Full setup wizard
claude-sync init --passphrase # Re-enter passphrase only (keeps storage config)
claude-sync init --force      # Reset everything, start fresh

Quiet Mode

claude-sync push -q     # No output (for scripts)
claude-sync pull -q

Check for Updates

claude-sync update --check   # Check without installing
claude-sync update           # Download and install latest version

Changelog

claude-sync changelog            # Show recent releases
claude-sync changelog --limit 5  # Show last 5 releases

Exclude Patterns

Skip specific files or directories during sync by adding exclude patterns to your config (~/.claude-sync/config.yaml):

exclude:
  - "*.tmp"
  - "projects/*/node_modules/*"
  - "projects/*/.git/*"

Patterns use glob syntax and are matched against paths relative to ~/.claude.

Shell Integration

Add to ~/.zshrc or ~/.bashrc: