claude-sync — own your sessions — move Claude Code sessions across machines. Part of Own Your Stack — own your AI infrastructure instead of renting it by the token.

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

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:

1. Path-hash mismatch. <encoded-cwd> is the absolute path with every non-alphanumeric character replaced by a single - (e.g. C:\Users\me\my app → C--Users-me-my-app). 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.
2. 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.

# 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

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

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.

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

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

When you pull, the receiving machine:

1. Scans <syncDir>/ for project subdirs.
2. For each, looks up the encoded key in its own projects.json.
3. If a local cwd is registered for that key, installs the session there.
4. 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).

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; the current release is deliberate-action only.

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.

.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 the current release understands; importers refuse unknown versions explicitly rather than silently dropping fields.

• Not a daemon. Push and pull are explicit user actions. Run a watcher yourself if you want background sync.
• Not a relay service. The current release ships only the filesystem transport — point it at any synced folder. SSH / S3 / gist / WebSocket transports would be straightforward additions; not shipped yet.
• 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.

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.

MIT — see LICENSE.

Part of Own Your Stack — open tools for owning your AI infrastructure instead of renting it by the token. One subscription. Your box. Your terms.

• dario — own your routing
• deepdive — own your research
• hands — own your computer-use
• agent — own your fleet
• browser-bridge — own your browser
• claude-sync — own your sessions (you are here)

Part of Own Your Stack — own your AI infrastructure instead of renting it. Built by Thomas Sprayberry.