Cross-device Claude session sync (manual push/pull merge via GCS)

[tim-codes]

Goal

When switching workstations, gather all Claude Code sessions/history/transcripts onto the current machine. Manual (or agent-invoked) trigger only — no background auto-sync (OneDrive-style) that could conflict with live sessions:

• on-finish-work → push: merge this machine's state up to shared storage
• on-pickup-work → pull: merge shared state down before starting

What syncs (per context: ~/.claude-personal, ~/.claude-exxo)

Same durable/runtime split scripts/claude-contexts --adopt-default and the exxo-personal overlay already draw:

• projects/ — transcripts + auto-memory (the payload that matters)
• history.jsonl — prompt history (needs line-union merge, not file copy)
• plans/, tasks/, todos/, file-history/, paste-cache/

Excluded: .claude.json (login/trust is per-machine), settings.json/CLAUDE.md/skills (claude-sync owns these from the repo), plugins (reinstallable snapshots), all runtime state (daemon, caches, session-env, shell-snapshots, sessions/). The ~/.claude-exxo-personal overlay needs nothing of its own — its durable state is symlinks into ~/.claude-exxo.

Proposed design: GCS bucket + advisory lock

One bucket (personal GCP project), one prefix per context: gs://<bucket>/claude-sync/<context>/....

Locking: GCS has no native lock API, but atomic lock-object creation via the if-generation-match=0 precondition is the standard advisory-lock pattern:

• acquire: gcloud storage cp lock.json gs://…/lock --if-generation-match=0 (fails atomically if held)
• lock body: {host, pid, timestamp}; stale after N minutes → steal with a warning
• release: delete on completion

Merge semantics:

• projects/ and other dirs: per-file newest-wins (gcloud storage rsync, no --delete-unmatched-destination-objects). Transcripts are uuid-named and effectively single-writer (a session runs on one machine), so real conflicts shouldn't occur; a same-file-both-newer clash is logged, never silently resolved.
• history.jsonl: download remote, line-union with local (dedupe on full line or (timestamp, sessionId)), upload merged, keep merged locally.
• Deletion does NOT propagate (rsync without delete) — cleanup/retention is a separate explicit operation.

Trigger surface: scripts/claude-session-sync <push|pull> [--context personal|exxo|all] in dotfiles, plus a small skill so any session can be told "I'm done on this machine" / "pick up from my other machine". Wrappers stay thin; explicit targets per the no-ambient-state rule; creds via the usual 1Password/esc reference flow — never a literal key.

Alternative considered: homelab hub (zima/ragnar) over rsync+ssh

No cloud dependency, data stays on-prem, ssh already trusted. Downsides: unavailable off-LAN/VPN when travelling with only laptops, and no cheap atomic lock primitive (flock over ssh works but is another moving part vs if-generation-match=0). GCS preferred; noting for the record.

Open questions

• Exxo transcripts in a personal GCP bucket — acceptable data governance, or does exxo context need an Exxo-owned bucket/prefix with its own credentials?
• Encryption: default at-rest is likely fine for personal; consider client-side (age) for the exxo prefix if governance demands.
• Desktop app session records (~/Library/Application Support/Claude-*/claude-code-sessions/) are per-machine and reference cwd paths — out of scope initially; CLI --resume over synced projects/ is the target UX. Machines must share identical repo paths (~/dev/...) for slugs to line up — true today; note as a constraint.
• Retention/pruning of the bucket copy (transcripts grow unbounded).

[tim-codes]

Additional measure under consideration: per-machine repo index (remote → local path)

Maintain a small per-machine index mapping remote repo identity (e.g. github.com/tim-codes/dotfiles) to its local checkout path. Rationale: session transcripts/state are effectively located by the session's repo cwd — the projects/<slug> dir is derived from the local path, and the transcripts embed cwd fields — so the repo is the natural stable key across machines while the local path is machine-specific incidental detail.

What the index buys the sync effort:

• Removes the identical-paths constraint (currently listed as an open-question constraint above). Push could translate machine-local slugs to a canonical repo-keyed layout in the bucket (gs://…/<context>/repos/<remote-id>/...); pull translates back to this machine's checkout path via the index — remapping both the slug dir name and the embedded cwd fields (same exact-string rewrite the worktree-closedown skill already does for worktree→primary relocation).
• Discovery/bootstrap: on pull, the index tells us which synced repos have no local checkout here — report them (or offer to clone to a chosen path) instead of silently dropping their sessions or materialising slugs for paths that don't exist.
• Non-repo cwds (e.g. ~/claude workspace sessions) fall through untranslated — those paths are already convention-identical across machines via dotfiles.

Implementation sketch: the index itself is mostly derivable rather than hand-maintained — walk known dev roots (~/dev, ~/claude) and read git remote get-url origin; cache the result per machine (it's machine state, not repo state — likely <context>-adjacent or ~/.local/state, NOT committed to dotfiles). A hand-curated overlay only for repos with no remote or ambiguous remotes.

Open sub-questions: canonical remote identity normalisation (ssh vs https forms of the same remote); repos with multiple checkouts/worktrees on one machine; whether the canonical bucket layout should be repo-keyed from day one even while all machines happen to share paths (cheaper than migrating later).

[tim-codes]

Design stance clarified (from discussion):

Path unification across workstations remains the intent — the convention-identical layout (~/dev/..., ~/claude) is the primary posture, not something the index replaces. The repo index's role is to harden that posture substantially, not to carry the sync on its own:

1. Verification: on push/pull, the index turns a silent path mismatch into a detected one — sync can assert that every repo it's about to sync resolves to the same canonical path on this machine as the convention expects, and stop loudly on divergence instead of scattering sessions under a wrong slug.
2. Translation as contingency: the slug/cwd remapping capability stays in the design (cheap once the bucket layout is repo-keyed), but it's the fallback path, not the paved one.

Escalation rule: if differing paths still present real problems in the sync work despite the index — i.e. translation proves fiddly or lossy in practice — then local path alignment gets promoted to a hard requirement in addition to the index: sync refuses to run against a non-conforming layout, and fixing the layout (moving the checkout, per the documented session-relocation procedure) becomes the prescribed remedy rather than something sync papers over.

Practical consequence for implementation order: build the index + verification first (small, useful immediately), keep the bucket layout repo-keyed from day one, and defer the translation machinery until/unless a real cross-machine divergence demands it.

[tim-codes]

Decided: local repo path alignment is a prerequisite, settled up front — not the escalation contingency of the previous comment. Consequences for the design:

1. Translation machinery is out of scope. No slug renaming or embedded-cwd rewriting in sync; with aligned paths the machine-local slugs are identical everywhere, so plain slug-keyed sync of projects/ works as-is. (The single-session relocation procedure remains documented for recovery, unrelated to sync.)

2. The index inverts from machine state to declared intent — and gains a bootstrap role. Since canonical paths are machine-independent now, the remote→path mapping is configuration, not per-machine cache — it belongs committed in dotfiles as a manifest (superseding the earlier "NOT committed" note, which applied to the per-machine-cache framing). Two operations against it:

   • Populate: on a workstation starting from an empty ~/dev, materialise the working set — clone each manifest repo to its canonical path (SSH remotes, consistent with the marketplace/plugin SSH rationale). Idempotent: existing conforming checkouts untouched.
   • Verify: assert every existing checkout sits at its canonical path and points at the expected remote; divergence is a loud error whose remedy is moving the checkout (session-relocation procedure if it hosted sessions), never papering over.
   • Manifest maintenance can stay semi-automatic: derive candidate entries by walking ~/dev on the reference machine (git remote get-url origin), then commit deliberately like any other dotfiles change.

3. Sequencing: repo manifest + populate/verify tool ships first (independently useful for machine bootstrap, same family as deps-up), then session sync builds on guaranteed-aligned paths and stays a dumb newest-wins file sync + history.jsonl line-union.

Open point carried over: whether Exxo repo remotes belong in a personal dotfiles manifest, or the manifest needs a per-context split mirroring the settings fragments (repos.shared / repos.exxo) — same shape as everything else claude-sync manages.

[tim-codes]

Refinement to the populate operation: support partial population for when the manifest grows large — cloning the full working set on every machine stops being appropriate at scale.

• Populate takes a selector rather than being all-or-nothing: by explicit repo name(s), by group/tag on the manifest entry (e.g. exxo, homelab, oss), or --all. Verify still runs against everything present regardless of how it got there.
• Manifest entries therefore carry an optional group/tag field from day one — cheap now, avoids a schema migration later.
• A lazy path composes naturally: pulling synced sessions for a repo that isn't checked out locally can offer to populate exactly that repo on demand, so a partially-populated machine still resumes anything.
• Un-populated manifest entries on a machine are a normal state, not a verify failure — verify flags only misplaced checkouts, never absent ones.

[tim-codes]

Accepted: Exxo repos live in the same single index — no per-context manifest split. Structure it by owner/org as the top level: tim-codes (personal) | <org-1> | <org-2> …, e.g.

tim-codes:
  dotfiles:  { path: ~/dev/dotfiles }
  homelab:   { path: ~/dev/homelab }
Exxo-Labs:
  exxo-infra: { path: ~/dev/exxo/exxo-infra }
  skills:     { path: ~/dev/exxo/skills }

Why this fits well:

• The owner is already the natural identity prefix of the canonical remote (github.com/<owner>/<repo>), so the structure is derivable, unambiguous, and gives owner-level defaults a home (e.g. a per-owner base path — ~/dev/ vs ~/dev/exxo/ — so most entries need no explicit path at all, matching the existing checkout convention).
• The owner doubles as the coarse populate selector (populate Exxo-Labs, populate tim-codes), covering most of the partial-population need; finer cross-cutting tags remain optional per-entry rather than primary structure.
• Only repo names/remotes are recorded — no secrets, so Exxo entries in the personal dotfiles repo are fine; anything sensitive stays out of the manifest by construction.

[tim-codes]

Forge-agnostic top level, per discussion: the grouping key is host-qualified owner, not a bare GitHub org — Exxo is planned to migrate to GitLab, and the manifest must not bake GitHub in.

github.com/tim-codes:
  base: ~/dev
  repos: { dotfiles: {}, homelab: {} }
gitlab.com/exxo:            # post-migration
  base: ~/dev/exxo
  repos: { exxo-infra: {}, skills: {} }

• host/owner is exactly the canonical remote prefix on any forge (GitHub, GitLab incl. subgroups, self-hosted), so derivation stays mechanical; GitLab subgroups just make the owner segment multi-part (gitlab.com/exxo/platform).
• This also subsumes the earlier remote-normalisation open question: the manifest stores one canonical host/owner/repo identity, and ssh/https remote URL forms are both recognised as that identity on verify (clone protocol is a separate per-host preference, default SSH per the existing plugin-refresh rationale).
• Migration is a manifest edit: move the entries to the new host/owner key, keep base/paths unchanged — local checkouts just get git remote set-url. Nothing in session sync notices, since sync is slug-keyed on local paths, which don't change. Verify flags checkouts still pointing at the old remote until they're repointed, which is the desired loud signal during a migration window.

[tim-codes]

Hard rule: git access is always SSH, never HTTPS — for every operation this issue's tooling performs (populate clones, git remote set-url during migration, verify's expected-remote check). Not a per-host preference as an earlier comment allowed: verify treats an HTTPS remote on any checkout as a violation to flag, and populate never emits one. Existing precedent generalised: the exxo-skills marketplace already had to be SSH because Claude Code's background plugin refresh disables git credential helpers and HTTPS fails on private repos — the same failure class applies to any unattended git operation this tooling will do.