Claude Session Sync

Sync your Claude Code sessions between machines with end-to-end encryption.

An MCP server that encrypts and syncs your ~/.claude/ data (history, todos, plans, and full project conversation context) across machines using a simple 6-word recovery phrase.

Why?

If you use Claude Code on multiple machines, you've felt the pain: your conversation history, todos, plans, and project context are stuck on whichever machine you used last. Claude Session Sync fixes that.

Security Model

Your data never leaves your machine unencrypted:

• 6-word BIP39 recovery phrase generates two separate keys
• Auth key — sent to server for identity verification (never the phrase itself)
• Encryption key — used locally for AES encryption, never transmitted
• Server stores only encrypted blobs — even the server operator can't read your data
• Gzip compression before encryption for efficient transfer

Quick Start

Install

npm install -g claude-session-sync

Add to Claude Code

claude mcp add claude-session-sync -- claude-session-sync

Or add manually to your MCP config:

{
  "mcpServers": {
    "claude-session-sync": {
      "command": "npx",
      "args": ["-y", "claude-session-sync"]
    }
  }
}

First Machine Setup

In Claude Code, say:

Set up session sync

Claude will run sync_setup which generates a 6-word recovery phrase:

+-------------------------------------------------------------+
|  RECOVERY PHRASE - SAVE THIS SECURELY!                      |
+-------------------------------------------------------------+
|                                                             |
|  apple banana cherry delta echo foxtrot                     |
|                                                             |
|  Write this down and store safely.                          |
|  You need this to sync on other machines.                   |
+-------------------------------------------------------------+

Then push your data:

Push my session data to sync

Second Machine Setup

Install the MCP server the same way, then in Claude Code:

Set up session sync with phrase "apple banana cherry delta echo foxtrot"

Then pull:

Pull my session from my other machine

Available Tools

Tool	Description
sync_setup	Initialize with a recovery phrase (new or existing)
sync_push	Encrypt and upload session data
sync_pull	Download and decrypt from another machine
sync_status	Show sync status across all machines
sync_list_machines	List registered machines
sync_list_projects	List local projects with sizes

Syncing Project Context

By default, only history, todos, and plans are synced (lightweight). To include full project conversation context:

Push my session data including the StarWhisper and Lunoo projects

This syncs the complete conversation context for those projects, so you can continue exactly where you left off on another machine.

Self-Hosting the Backend

The sync backend runs on Cloudflare Workers with KV + R2 storage. To self-host:

cd backend
npm install
# Edit wrangler.toml with your KV namespace ID and R2 bucket
wrangler deploy

Then point the client to your instance:

Set up session sync with server url "https://your-worker.workers.dev"

Storage Tiers

Tier	Storage	Machines
Free	100 MB	10
Pro	5 GB	10

What Gets Synced

Data	Priority	Strategy
history.jsonl	High	Incremental (new entries only)
todos/	High	Full sync per session
plans/	Medium	Full sync
projects/*.jsonl	Medium	Per-project selective
settings.json	Low	Full sync

Never synced: .credentials.json, API keys, machine-specific data

How It Works

Machine A                    Server                    Machine B
---------                    ------                    ---------
~/.claude/ data
    |
    v
Compress (gzip)
    |
    v
Encrypt (NaCl secretbox)
    |
    v
Upload encrypted blob ------> R2 Storage
                                  |
                        Download encrypted blob <------+
                                  |
                                  v
                          Decrypt (NaCl secretbox)
                                  |
                                  v
                          Decompress (gzip)
                                  |
                                  v
                          Merge into ~/.claude/

Merge Strategies

When pulling, you can choose how conflicts are handled:

• merge (default) — Combines data, remote wins on conflicts
• overwrite — Replaces local with remote
• ask — Reports conflicts without making changes

Requirements

• Node.js 18+
• Claude Code installed (~/.claude/ directory exists)

License

MIT