@askalf/claude-sync 0.0.3 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # @askalf/claude-sync
 
+> _claude-sync — own your sessions — move Claude Code sessions across machines. Part of **[Own Your Stack](https://github.com/askalf)** — 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.
 
 ```bash
@@ -19,8 +21,8 @@ Claude Code stores sessions locally at `~/.claude/projects/<encoded-cwd>/<sessio
 
 `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.
+- **Canonical project key** = `git:<host>/<owner>/<repo>`, derived from the git remote. Same logical repo → same key, regardless of where it's checked out or which protocol you cloned with — SSH and HTTPS remotes normalize to the same key. (Falls back to `name:<basename>` when there's no git remote.)
+- **You choose the cadence.** `push` from machine A and `pull` on machine B by hand, or run `claude-sync watch` to push-on-change and pull-on-interval automatically. The transport is either a local directory you nominate (Dropbox / iCloud / Syncthing / a USB stick) **or a directory on a remote host over SSH** (a dev box). Each machine writes its own file under its own machine name, so two machines pushing the same session don't collide.
 
 ## Use it
 
@@ -57,12 +59,80 @@ claude --resume sess-abc123
 
 That's the whole loop.
 
+### Or let it run: watch mode
+
+Tired of remembering to `push` and `pull`? Run a daemon per project:
+
+```bash
+cd ~/code/myapp
+claude-sync watch
+# claude-sync watch — desktop
+#   project:  git:github.com/you/myapp
+#   cwd:      /Users/you/code/myapp
+#   syncDir:  /Users/you/Dropbox/claude-sync
+#   every 10s · push most-recent changed session · pull all projects
+#   Ctrl-C to stop.
+#
+#   ↑ pushed sess-abc123 (142 lines)
+#   Imported sess-def456 from laptop → …/sess-def456.jsonl
+```
+
+Every interval (default 10s, `--interval <seconds>`) it pushes the active
+session whenever it has grown and pulls anything newer from your other
+machines. It watches the **most-recent** session by default; pass a session-id
+to pin one, or `--all` to push every changed session in the project. `--once`
+runs a single cycle and exits — handy from `cron`. Ctrl-C stops cleanly.
+
+It's still poll-based, not real-time co-editing: don't run the *same* session
+live on two machines at once (see [Concurrency](#concurrency)). Watch is for
+"pick up where the other machine left off without thinking about it."
+
+### Sync over SSH (no Dropbox needed)
+
+If you run Claude Code on a **dev server** and on a **laptop**, point the
+transport straight at a directory on the server — no third-party sync folder in
+the middle:
+
+```bash
+# On the laptop: the syncDir lives on the remote box, reached over SSH.
+claude-sync init --ssh me@devbox:/home/me/claude-sync --name laptop
+claude-sync doctor          # live connectivity + remote-dir check
+
+# On the server: a plain filesystem transport pointed at the same dir.
+claude-sync init /home/me/claude-sync --name devbox
+```
+
+Now `push` / `pull` / `watch` on the laptop shuttle sessions to and from the
+server with no manual `scp`. Options: `--port <n>`, `--identity <keyfile>`.
+It uses your system `ssh`, honors your `~/.ssh/config`, runs in `BatchMode`
+(so it fails fast instead of prompting), and multiplexes connections on
+macOS/Linux so a `pull`'s round-trips share one SSH session.
+
+> The remote layout is identical to the filesystem transport, so the server's
+> `fs` transport and the laptop's `ssh` transport — both pointed at
+> `/home/me/claude-sync` — interoperate. The remote host needs a POSIX shell
+> with `find`/`tar` (any Linux box).
+
+### Starting on a fresh clone
+
+`pull` can only deliver a session to a directory it knows about. On a machine
+that has never had a session for this project yet, register the directory once:
+
+```bash
+cd ~/code/myapp
+claude-sync register   # binds this cwd to the project key — no session needed
+claude-sync pull       # now resolves
+```
+
+(`watch` registers automatically on start, and `import … --cwd <path>` registers
+the target, so you usually only need `register` for a manual `pull`-first flow.)
+
 ## How path resolution works
 
 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`.
+2. Canonicalizes it into a project key: `git:github.com/you/myapp` (SSH and HTTPS remotes land on the same key).
 3. Registers the local cwd under that key in `~/.claude-sync/projects.json`.
 4. Writes the `.ccsync` into `<syncDir>/<encoded-key>/<session>-<machine>.ccsync`.
 
@@ -71,36 +141,37 @@ 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.
+4. If not — claude-sync hasn't seen this project on this machine yet — it skips with a warning. Run `claude-sync register` in the cwd once (binds the key, no session needed), or `claude-sync import <file> --cwd <path>` to install a specific file (which also registers the directory).
 
-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).
+In practice: clone the repo on the new machine, `cd` in, `claude-sync register`, then `claude-sync pull`. Or just start `claude-sync watch`, which registers on launch.
 
 ## 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:
+`watch` automates *when* to push and pull, but it's still poll-based, not a locking protocol. If two machines edit the **same** session concurrently:
 
 - 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.
+So: use `watch` to hand a project *back and forth* between machines hands-free; don't drive the same live session from two machines at once. A lock-file protocol for true real-time co-editing is a possible future addition.
 
 ## CLI reference
 
 ```text
 claude-sync init <syncDir> [--name <machine>]
+claude-sync init --ssh <[user@]host:/path> [--port <n>] [--identity <keyfile>] [--name <machine>]
 claude-sync list
+claude-sync register [cwd]
 claude-sync export [session-id] [-o <file>]
 claude-sync import <file> [--cwd <path>] [--overwrite]
 claude-sync push [session-id]
 claude-sync pull
+claude-sync watch [session-id] [--interval <seconds>] [--all] [--once]
 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.
+`doctor` prints config, machine name, registered projects, and transport peers — and warns if any registered cwd no longer exists on disk, or if every file in the transport carries this machine's own name (which makes `pull` a silent no-op — give each machine a distinct `--name`).
 
 ## File format
 
@@ -110,7 +181,7 @@ claude-sync --help / --version
 {
   "_schemaVersion": 1,
   "sessionId": "...",
-  "projectKey": "git:https://github.com/you/myapp.git",
+  "projectKey": "git:github.com/you/myapp",
   "originalCwd": "C:\\Users\\you\\code\\myapp",
   "machineName": "desktop",
   "exportedAt": 1715380000000,
@@ -119,13 +190,12 @@ claude-sync --help / --version
 }
 ```
 
-Schema-versioned. Version 1 is the only thing v0.0.1 understands; importers refuse unknown versions explicitly rather than silently dropping fields.
+Schema-versioned. Version 1 is the only thing the current release 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 real-time co-editing.** `watch` polls on an interval; it isn't a locking protocol. If both machines drive the *same* session simultaneously, the second to sync overwrites the other's in-progress copy (the loser is kept as `<id>-copy.jsonl`). Use it to hand a project between machines, not to co-edit one session live.
+- **Not a relay service.** Two transports ship — a local synced folder and a remote directory over SSH. There's no hosted relay; S3 / gist / WebSocket transports would be straightforward additions on the `Transport` interface, but aren't shipped yet.
 - **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
@@ -134,13 +204,21 @@ For embedders (custom transports, watch daemons, etc.):
 
 ```ts
 import {
-  listSessions, readSession, writeSession,
+  listSessions, listSessionStats, countSessionLines, readSession, writeSession,
   buildCcsync, parseCcsync, readCcsyncFile, writeCcsyncFile,
-  projectKey, registerProject, lookupCwd,
-  pushToTransport, listTransport,
+  projectKey, normalizeGitRemote, registerProject, registerProjectKey, lookupCwd,
+  // Transports: the abstraction + both backends.
+  createTransport, resolveTransportConfig, FsTransport, SshTransport,
+  type Transport, type TransportConfig,
 } from '@askalf/claude-sync';
 ```
 
+Everything is built on these exports — `listSessionStats` for cheap change
+detection, the `Transport` interface (`push` / `listEntries` / …) for the sync,
+`registerProject` for first-contact. A custom transport is one class
+implementing `Transport`; `SshTransport` takes an injectable `SshExecutor`, so
+you can wrap it or swap the wire entirely.
+
 See `src/index.ts` for the full surface. Zero runtime dependencies.
 
 ## Environment
@@ -153,27 +231,16 @@ See `src/index.ts` for the full surface. Zero runtime dependencies.
 
 MIT — see [LICENSE](LICENSE).
 
-## Also by askalf
+## Own Your Stack
 
-| Project | What it does |
-|---------|-------------|
-| [arnie](https://github.com/askalf/arnie) | Portable IT troubleshooting companion. Networking, AD, Windows Update, package managers, log triage, hardware checks. |
-| [brio](https://github.com/askalf/brio) | Capability layer for AI workloads — semantic cache, cost tiering, policy. Sits in front of any Anthropic-compat endpoint. |
-| [browser-bridge](https://github.com/askalf/browser-bridge) | Stealth headless Chromium in a container. CDP on 9222 — Playwright/Puppeteer/MCP-compatible. |
-| [claude-bridge](https://github.com/askalf/claude-bridge) | Bridge Claude Code sessions to Discord. |
-| [dario](https://github.com/askalf/dario) | Local LLM router. Use your Claude Max/Pro subscription as an API. |
-| [deepdive](https://github.com/askalf/deepdive) | Local research agent. Plan → search → fetch → extract → synthesize. Cited answers. |
-| [git-providers](https://github.com/askalf/git-providers) | Unified GitHub + GitLab + Bitbucket Cloud REST clients behind one GitProvider interface. Plus a 44-entry api-key-provider taxonomy. |
-| [hands](https://github.com/askalf/hands) | Cross-platform computer-use agent. Mouse, keyboard, screen. |
-| [install-kit](https://github.com/askalf/install-kit) | curl-pipe-bash template for self-hosted Docker apps. |
-| [pgflex](https://github.com/askalf/pgflex) | One Postgres API. Two modes (real PG ↔ PGlite WASM). |
-| [redisflex](https://github.com/askalf/redisflex) | One Redis API. Two modes (ioredis ↔ in-process). |
+Part of **[Own Your Stack](https://github.com/askalf)** — open tools for owning your AI infrastructure instead of renting it by the token. One subscription. Your box. Your terms.
 
+- **[dario](https://github.com/askalf/dario)** — own your routing
+- **[deepdive](https://github.com/askalf/deepdive)** — own your research
+- **[hands](https://github.com/askalf/hands)** — own your computer-use
+- **[agent](https://github.com/askalf/agent)** — own your fleet
+- **[browser-bridge](https://github.com/askalf/browser-bridge)** — own your browser
+- **claude-sync** — own your sessions _(you are here)_
 
 ---
-
-## Built by Sprayberry Labs
-
-This is one of the open-source building blocks from **[Sprayberry Labs](https://sprayberrylabs.com)** — an independent studio (Atlanta, GA) that ships bespoke software and **fixed-price code & security audits**, delivered with the AI workforce these tools are part of.
-
-**Got a codebase that needs an expert read?** → **[Scan a repo — free mini-audit](https://sprayberrylabs.com)**, or see the **$1,500 fixed-price Audit** and build Sprints. · [sprayberrylabs.com](https://sprayberrylabs.com) · hello@sprayberrylabs.com
+Part of **[Own Your Stack](https://github.com/askalf)** — own your AI infrastructure instead of renting it. Built by Thomas Sprayberry.

package/dist/cli.d.ts

@@ -5,10 +5,12 @@
  * Subcommands:
  *   init <syncDir> [--name <machine>]    scaffold ~/.claude-sync/config.json
  *   list                                 list local CC sessions for the cwd
+ *   register [cwd]                       register a cwd's project key (no session needed)
  *   export [session-id] [-o <file>]      pack a session into a .ccsync file
  *   import <file> [--cwd <path>]         install a .ccsync file locally
  *   push [session-id]                    export + ship to configured syncDir
  *   pull                                 import any newer .ccsync files
+ *   watch [session-id] [--interval <s>]  daemon: auto-push changes + auto-pull peers
  *   doctor                               diagnose config + registry health
  *
  * Common flags: --help, --version. No external arg-parser dep — the

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG"}