@askalf/claude-sync

@askalf/claude-sync

Sync Claude Code sessions across machines. Pack a session into a portable .ccsync file, ship it via Dropbox / iCloud / Syncthing / a USB stick, unpack on the other side. Path-hash mismatches solved via git-remote-url as the canonical project key.

npm install -g @askalf/claude-sync

Why

Claude Code stores sessions locally at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. There's no native cross-machine sync. The naive workaround — rsync ~/.claude/projects/ — has two problems:

• Path-hash mismatch. <encoded-cwd> is the absolute path with [/\\:.\s]+ collapsed to -. Same git repo at /Users/alice/code/myapp (mac) and D:\code\myapp (windows) hashes to different directory names → the synced session is orphaned on arrival.
• No file locking. Concurrent writes from two machines into the same JSONL corrupt the transcript.

claude-sync solves both:

• Canonical project key = git:<remote-url>. Same logical repo → same key, regardless of where it's checked out. (Falls back to name:<basename> when no git remote.)
• Single-writer model. You explicitly push from machine A, then pull on machine B. No background daemon racing files. The transport is a directory you nominate (Dropbox / iCloud / Syncthing / a USB stick); each machine writes its own file under its own machine name, so two machines pushing the same session don't collide.

Use it

One-time setup, on each machine

# Point claude-sync at a directory that's mirrored across machines.
# Anything Dropbox / iCloud / Syncthing / OneDrive sync, or a network
# share. Doesn't matter what — claude-sync just reads + writes here.
claude-sync init ~/Dropbox/claude-sync --name desktop

# On the other machine:
claude-sync init ~/Dropbox/claude-sync --name laptop

Push a session

cd ~/code/myapp
claude  # ... do work ...
# When you're switching machines:
claude-sync push
# → Pushed sess-abc123 → ~/Dropbox/claude-sync/git-https---github-com-you-myapp-git/sess-abc123-desktop.ccsync

Pull on the other machine

cd ~/code/myapp
claude-sync pull
# → Imported sess-abc123 from desktop → ~/.claude/projects/-Users-laptop-code-myapp/sess-abc123.jsonl
claude --resume sess-abc123

That's the whole loop.

How path resolution works

When you push from a project with a git remote, claude-sync:

• Reads git remote get-url origin from your cwd.
• Builds a project key: git:https://github.com/you/myapp.git.
• Registers the local cwd under that key in ~/.claude-sync/projects.json.
• Writes the .ccsync into <syncDir>/<encoded-key>/<session>-<machine>.ccsync.

When you pull, the receiving machine:

• Scans <syncDir>/ for project subdirs.
• For each, looks up the encoded key in its own projects.json.
• If a local cwd is registered for that key, installs the session there.
• If not — claude-sync hasn't seen this project on this machine yet — it skips with a warning. You either push once from the right cwd to register it, or run claude-sync import <file> --cwd <path> explicitly.

In practice: clone the repo on the new machine, cd in, run claude-sync push once with no real session (it'll error if there's no session — that's fine), then run claude-sync pull to fetch. The first push registers the cwd.

A cleaner way: just run any claude command in the cwd once, then claude-sync export (which registers without pushing).

Concurrency

There's no daemon and no automatic background sync. You decide when to push and when to pull. If you forget and edit the same session on both machines:

• Two .ccsync files end up in <syncDir>/<project>/, named with each machine's name.
• The receiving pull skips files older or shorter than the local copy.
• Newer/longer files install with --overwrite. The losing machine's edits become a <session-id>-copy.jsonl (you can manually inspect + reconcile).

Future versions may add a watch-mode + lock-file protocol for "real-time" sync; v0.0.1 is deliberate-action only.

CLI reference

claude-sync init <syncDir> [--name <machine>]
claude-sync list
claude-sync export [session-id] [-o <file>]
claude-sync import <file> [--cwd <path>] [--overwrite]
claude-sync push [session-id]
claude-sync pull
claude-sync doctor
claude-sync --help / --version

doctor prints config, machine name, registered projects, and warns if any registered cwd no longer exists on disk.

File format

.ccsync is a small JSON wrapper around the JSONL session content:

{
  "_schemaVersion": 1,
  "sessionId": "...",
  "projectKey": "git:https://github.com/you/myapp.git",
  "originalCwd": "C:\\Users\\you\\code\\myapp",
  "machineName": "desktop",
  "exportedAt": 1715380000000,
  "lineCount": 142,
  "jsonl": "<the entire session JSONL>"
}

Schema-versioned. Version 1 is the only thing v0.0.1 understands; importers refuse unknown versions explicitly rather than silently dropping fields.

What it isn't

• Not a daemon. Push and pull are explicit user actions. Run a watcher yourself if you want background sync.
• Not a relay service. v0.0.1 ships only the filesystem transport — point it at any synced folder. SSH / S3 / gist / WebSocket transports would be straightforward additions; not in v0.0.1.
• Not real-time. If both machines are CC-active simultaneously, the second to pull overwrites their in-progress session unless they noticed and stopped first. Use one machine at a time.
• Not a CC re-implementation. It just shuffles JSONL. CC's session schema can change without breaking claude-sync — we never parse the events.

Library API

For embedders (custom transports, watch daemons, etc.):

import {
  listSessions, readSession, writeSession,
  buildCcsync, parseCcsync, readCcsyncFile, writeCcsyncFile,
  projectKey, registerProject, lookupCwd,
  pushToTransport, listTransport,
} from '@askalf/claude-sync';

See src/index.ts for the full surface. Zero runtime dependencies.

License

MIT — see LICENSE.

Also by askalf

Project	What it does
arnie	Portable IT troubleshooting companion. Networking, AD, Windows Update, package managers, log triage, hardware checks.
brio	Capability layer for AI workloads — semantic cache, cost tiering, policy. Sits in front of any Anthropic-compat endpoint.
browser-bridge	Stealth headless Chromium in a container. CDP on 9222 — Playwright/Puppeteer/MCP-compatible.
claude-bridge	Bridge Claude Code sessions to Discord.
dario	Local LLM router. Use your Claude Max/Pro subscription as an API.
deepdive	Local research agent. Plan → search → fetch → extract → synthesize. Cited answers.
git-providers	Unified GitHub + GitLab + Bitbucket Cloud REST clients behind one GitProvider interface. Plus a 44-entry api-key-provider taxonomy.
hands	Cross-platform computer-use agent. Mouse, keyboard, screen.
install-kit	curl-pipe-bash template for self-hosted Docker apps.
pgflex	One Postgres API. Two modes (real PG ↔ PGlite WASM).
redisflex	One Redis API. Two modes (ioredis ↔ in-process).