Syncing

How Sync Works

claude-sync uses a manifest-based diffing approach to synchronize only what's changed. When you push or pull, the CLI generates a manifest (a SHA-256 hash map of all your local files), sends it to the API, and the API compares it against the cloud state. Only files that are new or modified are uploaded or downloaded, minimizing bandwidth and storage.

The sync Command

The simplest way to sync is with the sync command, which performs both a push and a pull:

⬆️  Pushing local changes...
   ✔ Uploaded 3 new sessions
   ✔ Updated 1 session

⬇️  Pulling remote changes...
   ✔ Downloaded 2 sessions from Linux Desktop
   ✔ Sync complete!

Pushing Sessions

To only upload your local changes without pulling:

The CLI builds a manifest of all sessions, todos, artifacts, and tool-results in your ~/.claude directory, sends it to the API, and the API responds with a list of files that need to be uploaded. The CLI then uploads those files to MinIO storage using presigned URLs and finalizes the sync.

Pulling from Another Device

To download sessions from a specific device:

⬇️  Pulling from Linux Desktop...
   ✔ Fetched remote manifest (42 sessions)
   ✔ Downloading 5 changed files...
   ✔ Downloaded 5 files (1.2 MB)
   ✔ Symlinks updated
   ✔ Pull complete!

The CLI fetches the remote manifest for the specified device, compares it to your local state, downloads any missing or updated files, and creates symlinks as needed for cross-machine path resolution.

Checking Status

View your current sync state without making any changes:

API: https://api.claude-sync.com
User: dev@company.io
Device: MacBook Pro (d8f3a2b1-7c4e-4a9f-b5d1-3e8f6a2c9d04)
Project: /Users/dev/myapp

Local State:
  • 15 sessions
  • 3 todos
  • 8 artifacts
  • Last synced: 2026-02-05 10:23:11

Remote State:
  • 17 sessions across 2 devices
  • 2 sessions need pulling
  • 1 session needs pushing

Flags

Control sync behavior with optional flags:

• --dry-run — Preview what would be synced without making changes
• --verbose — Show detailed output including file-by-file progress
• --project — Sync a specific project directory instead of all projects

What Gets Synced

claude-sync uploads and downloads the following from your ~/.claude/projects/ directory:

• Session JSON files (sessions/*.json)
• Tool result files (tool-results/*)
• Subagent session data (subagent-sessions/*)
• Plans (plans/*.json)
• Todos (todos/*.json)
• Artifacts (artifacts/*)

Excluded Files

The following patterns are automatically excluded from sync:

node_modules/
.git/
.DS_Store
.env
.env.*
*.log
.claude-sync/
dist/
build/
.next/
.turbo/