Personalization sync

Cross-machine sync of the operator’s Claude Code state — global config, per-project memory, spec/superpower outputs, and workspace planning notes — through a separate (typically private) GitHub repo. ctrlrelay clones that repo into a checkout, lays down symlinks at the right places, and rebases onto a per-machine branch so two computers pushing concurrently never overwrite each other’s deltas.

The personalization repo is not the same as the project repos in repos:. It’s an out-of-tree store for things that survive across sessions and machines but don’t belong inside any project’s source tree.

Why this exists

Without sync, the operator hits three problems:

  1. ~/.claude/CLAUDE.md, skills, agents, commands drift between machines. Edits on the laptop don’t reach the workstation.
  2. Per-project memory under ~/.claude/projects/<encoded>/memory/ is lost the moment you switch machines. Claude has to relearn the project from scratch every time.
  3. Spec / superpower outputs that Claude writes per project would be either lost (if kept under ~/), polluting (if committed inside the project repo), or invisible to other machines.

A second git repo solves all three cleanly. The cost is one private repo per operator, plus a personalization: block in orchestrator.yaml.

Layout: the dotclaude repo

The repo can be named anything, but the convention is <your-handle>/dotclaude or similar. The example layout this doc assumes:

dotclaude/
├── global/
│   ├── CLAUDE.md          # ~/.claude/CLAUDE.md
│   ├── skills/            # ~/.claude/skills/
│   ├── agents/            # ~/.claude/agents/
│   ├── commands/          # ~/.claude/commands/
│   └── keybindings.json
├── claude-memory/
│   └── <owner>--<repo>/   # ~/.claude/projects/<encoded>/memory/
└── specs/
    └── <owner>--<repo>/   # <project-parent>/specs/<owner>--<repo>/

The <owner>--<repo> slug uses a double hyphen as the owner/repo separator so a-b/c and a/b-c produce different slugs (a-b--c vs. a--b-c) and never collide.

Why a directory next to the project for specs, not inside it: the project’s own git history must stay uncontaminated. Spec docs Claude writes during development belong to your operator state, not to the project’s commit log.

One-time setup

1. Create the personalization repo

Create an empty private GitHub repo. The gh CLI is fine:

gh repo create your-handle/dotclaude --private --description \
  "Cross-machine sync of Claude Code personalization (config, memory, specs) — managed by ctrlrelay"

Don’t add a README, .gitignore, or license — ctrlrelay’s init will populate it.

2. Configure personalization: in orchestrator.yaml

personalization:
  repo: "your-handle/dotclaude"
  # checkout_path: "~/.ctrlrelay/personalization"   # default
  # main_branch: "main"                              # default
  # node_id: "studio-mac"                            # default: top-level node_id
  paths:
    - source: "global/CLAUDE.md"
      target: "~/.claude/CLAUDE.md"
    - source: "global/skills/"
      target: "~/.claude/skills/"
    - source: "global/agents/"
      target: "~/.claude/agents/"
    - source: "global/commands/"
      target: "~/.claude/commands/"

    # Per-project memory. Placeholders resolve from each repo's
    # local_path at link time, so the same config works on machines
    # with different home directories or repo layouts.
    - source: "claude-memory/${PROJECT}/"
      target: "~/.claude/projects/${PROJECT_ENCODED}/memory/"
      project_scoped: true

    # Spec / superpower outputs Claude writes per project, kept
    # NEXT TO the repo (not inside it).
    - source: "specs/${PROJECT}/"
      target: "${PROJECT_PARENT}/specs/${PROJECT}/"
      project_scoped: true

Trailing slashes matter: source: "global/CLAUDE.md" is treated as a file, source: "global/skills/" is treated as a directory. The target must agree — a mismatch is rejected with skipped-target-type-mismatch.

Path placeholders

Use these in source and target. ${PROJECT_*} placeholders only work when project_scoped: true.

Placeholder Resolves to
${HOME} Current user’s home (target only)
${PROJECT} <owner>--<repo> flat slug
${PROJECT_ENCODED} Claude’s path encoding of the repo’s local_path
${PROJECT_LOCAL} Absolute path of the repo’s local checkout
${PROJECT_PARENT} Parent dir of ${PROJECT_LOCAL}

${PROJECT_ENCODED} matches the way Claude Code itself encodes paths into ~/.claude/projects/: /Users/foo/Projects/bar → -Users-foo-Projects-bar. ctrlrelay computes it from each repo’s local_path so the same config works across machines with different home directories.

3. Run init

ctrlrelay personalization init

This:

  1. Clones your-handle/dotclaude into ~/.ctrlrelay/personalization.
  2. Creates a per-machine working branch named personalization/<node_id> (or fast-forwards to it if it already exists on the remote).
  3. Walks the paths list and lays down symlinks. Adopt-flow is on by default: when a target like ~/.claude/CLAUDE.md already exists as a real file but the corresponding source slot in the repo is empty, the existing target is moved into the repo and a symlink is wired in its place. Your content is preserved and immediately under sync.

Pass --no-adopt to opt out of adoption and keep the conservative “refuse to touch any pre-existing real path” behavior:

ctrlrelay personalization init --no-adopt

With --no-adopt, pre-existing real targets surface as skipped-real-file-at-target and you back them up + remove them before re-running init.

After init, run push once so the adopted content reaches GitHub:

ctrlrelay personalization push -m "initial personalization import from <hostname>"

Day-to-day commands

personalization status

ctrlrelay personalization status

Prints the working branch, repo URL, ahead/behind counts vs. origin, and the per-symlink state — correct, wrong-target, missing, source-missing, etc. — without touching the filesystem.

personalization push

ctrlrelay personalization push -m "added a new skill"

Stages everything inside the allowlist (the entries declared in paths), commits, rebases the per-machine branch onto origin/main, and pushes. If origin/main advanced between your fetch and your push, the FF is retried up to three times so concurrent edits from your other machine don’t strand your commit.

--force-with-lease is used on the per-machine branch when the local working branch has diverged from origin/<working_branch> (i.e. the rebase rewrote commits the remote already had). Per-machine branches are owned by exactly one node by design, so the lease almost always passes; if a stray update slips in, the push fails safely instead of clobbering it.

personalization pull

ctrlrelay personalization pull

Fetches, rebases your per-machine branch onto origin/main, fast- forwards your local main if it’s a strict ancestor of the remote, and re-wires symlinks (the config-as-code shipped in the repo may have changed). Conflicts during the rebase abort cleanly and list the unmerged files — resolve in the checkout, then re-run.

Auto-pull on cron

Set schedules.personalization_cron to converge machines without manual sync:

schedules:
  secops_cron: "0 6 * * *"
  personalization_cron: "*/15 * * * *"   # every 15 min

The poller registers an APScheduler job that runs personalization pull on this schedule. Two safety rails:

  • Refuse-on-dirty, loudly. If the working tree has uncommitted changes, the auto-pull does not rebase (a daemon rebasing under your unsaved edits is exactly the surprise we don’t want) but it is not a quiet success: the run fails, is logged at error level as auto-pull BLOCKED: working tree dirty (...), and names the dirty entries. It still fetches, so the line carries behind N. Every run reports behind N; a machine drifting is a number in the log, not silence (#287: one machine sat 36 commits behind for weeks).
  • No adoption. Adoption is an init-time concern. The auto-pull re-wire phase runs with adopt=False so a background sync never silently moves files. New entries in paths that have no remote source yet stay as skipped-source-missing until you init again.

Auto-push is intentionally not scheduled. A daemon committing on the operator’s behalf without explicit intent is the kind of thing that surprises people; commits stay manual.

Multi-machine bootstrap

On the second machine:

  1. Install ctrlrelay, copy your orchestrator.yaml over (the personalization: block must be identical except for node_id if you set it explicitly).
  2. ctrlrelay personalization init.
  3. Done. The clone fast-forwards personalization/<this-machine> from origin/main, lays the symlinks down on top of your existing ~/.claude/ (adopting where empty, refusing where both sides have real content), and you’re synced.

If the second machine already has a populated ~/.claude/CLAUDE.md that differs from the one on the first machine, you’ll get skipped-conflict-both-exist for that path. Pick a winner manually (diff, copy the chosen content into the repo source, delete the loser’s local), then re-run init.

Per-machine branches and the FF dance

Each machine commits to personalization/<node_id>. push rebases that branch onto origin/main, then fast-forwards origin/main from the per-machine branch. Two machines pushing concurrently:

A: main = X
A: personalization/a = X + a1
A: push  -> rebases on X, ff main: main = X + a1

B: main = X (stale)
B: personalization/b = X + b1
B: push  -> fetch sees main = X + a1
         -> rebases b1 on top: main + b1
         -> ff main: main = X + a1 + b1   (succeeds, retry not needed)

If both machines fetch at the exact same instant and both push, only one wins the FF; the other retries up to three times. No force-push to main is ever attempted.

Gotchas

Worktrees inside the personalization checkout

Don’t create git worktrees inside ~/.ctrlrelay/personalization. The checkout is a single working copy of a single per-machine branch. Worktrees would attach to the same .git and confuse status / pull. ctrlrelay’s per-repo worktrees (paths.worktrees) are an unrelated, project-scoped feature.

A write to ~/.claude/CLAUDE.md is a write to ~/.ctrlrelay/personalization/global/CLAUDE.md. After editing, run ctrlrelay personalization push. If you forget, the auto-pull’s refuse-on-dirty rail keeps things safe — the daemon won’t rebase under your unsaved work and says so at error level — but your edit doesn’t reach other machines until you push.

Files an app rewrites in place (settings.json): mode: merge

If a target such as ~/.claude/settings.json is a symlink into the checkout, the app that owns it writes straight into a tracked file: any per-viewer preference it records (and a mere key reordering on rewrite) dirties the tree and blocks every later pull. Committing those keys is wrong too, because one machine’s preference would reach every machine as if it were policy.

So for such a file, declare the entry with mode: merge and list the top-level keys the fleet owns:

personalization:
  paths:
    - source: "global/settings.json"
      target: "~/.claude/settings.json"
      mode: merge
      merge_keys: [model, outputStyle, hooks, teammateMode,
                   remoteControlAtStartup, skipDangerousModePermissionPrompt,
                   idleCompaction]

The live file is then a real file on this machine, never a symlink. On init, pull and the daemon’s auto-pull, ctrlrelay writes into it only the listed keys that the synced file carries, and reports what it did on the same line as the pull: settings: wrote model, outputStyle, or settings: in-sync. Everything else in the live file, including whatever the app wrote on its own, is left as it is and never reaches the checkout.

The rules, all enforced and tested:

  • The key list is local. merge_keys lives in orchestrator.yaml on each machine, not in the synced repo, so a push to that repo cannot widen what it controls. A key in the synced file that is not listed is not written. (Keep orchestrator.yaml itself out of the synced repo, or this guarantee is gone.)
  • An owned key missing upstream is left alone, not deleted: absent is not the same as “remove it”. To change a value fleet-wide, set it.
  • Bad input is refused. The synced file must parse as a JSON object with no duplicate keys, at any depth, and so must the live file (an empty live file counts as {}). Nesting too deep to parse is refused the same way. Anything else leaves the live file untouched and logs an error.
  • Everything stays under $HOME. The live file and the personalization checkout must both be under your home directory; a path outside it is refused with is not under $HOME. (The default checkout, ~/.ctrlrelay/personalization, is.)
  • Links and odd files are refused. Directories are opened one component at a time without following links (O_DIRECTORY | O_NOFOLLOW), starting at the resolved $HOME, so a home reached through an alias (macOS /var -> /private/var) works. The read, the temp file and the rename all go through that directory handle. So a symlink at the file or at any directory under $HOME on the way to it is refused, and its target is never opened. A symlinked ~/.claude is therefore refused too. Both files must be regular files owned by you, so a FIFO or someone else’s file is refused as well. The live path, with its directories resolved, must sit outside the checkout.
  • Writes are atomic. Temp file in the same directory, fsync, rename over the live path; mode 0600, or the existing mode if it is stricter.
  • A concurrent app write is not lost silently. Just before the rename, the live file is checked to still be what was read (device, inode, size, mtime). If the app wrote it in between, the merge is redone once from the new content; if it changed again, the pull refuses and the app’s write stands. Known limit: a write landing in the few instructions between that last check and the rename itself can still be overwritten, as can one that changes neither size nor mtime. No user-space check can close that window without the app taking a lock.
  • Values too deep to handle are refused, whether the parser rejects them or they parse but are too deep to compare or write back.
  • What keeps app-written keys out of the repo, exactly. The live file is a real file outside the checkout, so nothing the app writes to it is in the git working tree at all. That is the guarantee.
  • Push refuses a changed checkout copy. If a merge entry’s checkout copy differs from HEAD in any way (modified, staged, deleted, renamed away, or present but untracked), push refuses before staging anything and leaves the file alone: refusing to push: global/settings.json in the checkout differs from HEAD. This file is fleet policy; to change it for every machine, commit it yourself with git in the checkout; to drop the local change, run ctrlrelay personalization migrate --reset-copy. After staging, push also unstages every merge-mode file and checks the index (ignoring case where git does), refusing if one is still staged. These push checks are a backstop against accidental staging.
  • What this does not cover: deliberate local edits in the checkout. Anyone who can write the checkout can already publish anything from it, so these are out of scope by design, not gaps to close:
    • renaming the copy (git mv global/settings.json ... and committing);
    • copying it elsewhere in a synced directory (cp global/settings.json global/other.json), which pushes the copy as an ordinary file;
    • hiding a change from git with git update-index --assume-unchanged or --skip-worktree on the copy;
    • committing to the checkout by hand (git commit), which push then publishes like any other commit.
  • Whatever is committed in the checkout goes to every machine. To change fleet settings, edit global/settings.json in the checkout and git commit it yourself; push publishes that commit like any other, and every machine applies it within its own merge_keys. ctrlrelay does not inspect such a commit, so never commit a value that belongs to one machine.
  • Only HEAD’s fleet values reach the live file. A merge (on pull, init or migrate) is refused while the checkout copy differs from HEAD, and migrate --reset-copy resets the copy before merging, so a local edit to a fleet key is never applied to the live file. If git cannot answer whether the copy differs, push and merge refuse (could not check global/settings.json: ...) rather than assume.
  • Without merge entries nothing changes. A configuration with no mode: merge entry stages and commits on push exactly as before.
  • Logs name keys, never values (a value can be a secret under env). A pull that changes hooks, env, permissions, apiKeyHelper or skipDangerousModePermissionPrompt logs a warning naming the key, so a surprise change is visible.

A refusal makes the pull fail (settings: REFUSED (...)), so a machine that cannot apply fleet settings says so rather than looking synced.

A machine wired before this has ~/.claude/settings.json as a symlink into the checkout. pull and auto-pull refuse that link and say so; they never convert it themselves. Convert it once, explicitly:

ctrlrelay personalization migrate

This replaces the link with a real file holding the same content (so anything the app or you wrote through it stays on this machine). Once the new live file is confirmed to match, it resets the checkout copy to HEAD, the fleet’s version, so the tree is clean and those local keys can never be pushed; the output names the keys it reset, never their values. Then it merges. A link that points anywhere other than this checkout’s source is refused.

ctrlrelay personalization migrate --reset-copy additionally drops any remaining local change to a merge entry’s checkout copy (resetting it to HEAD; the output names the keys, never the values). It is the way out of a push refused because that copy changed. It refuses while the live path is still the old symlink, since the copy is then the live file.

Anything outside ctrlrelay that recreates the symlink (a converge script, a dotfiles installer) must stop doing so for this file, or the next pull will refuse again.

Git identity

push pre-flights the author identity before staging: it falls back to a repo-local ctrlrelay <ctrlrelay@local> when none is configured, then asks git (git var GIT_AUTHOR_IDENT) and refuses with git identity unresolvable if it still cannot commit, rather than leaving a dirty tree behind.

Allowlist enforcement

Only the entries declared in paths are staged on push. Random files dropped into the checkout (a stray .DS_Store, a temp note) are not committed. This is intentional: the personalization repo is the operator’s, not Claude’s, and “everything that’s there” is not the right granularity.

Conflict during auto-pull

If a scheduled auto-pull hits a rebase conflict (someone pushed an edit to the same file from another machine while a local commit was pending), the rebase aborts and the conflict files appear in the poller log. Resolve manually with ctrlrelay personalization pull, which surfaces the same files in your terminal.

Repo URL match is strict

init verifies the existing checkout’s origin URL is exactly github.com:<your-handle>/<repo> before treating it as “ours” for re-init. A mismatch refuses to proceed — back up or remove the checkout before running init.

Privacy

The personalization repo holds your Claude memory, skills, and per- project notes. Treat it like any other operator-private store:

  • Make the repo private. gh repo create --private.
  • Don’t put secrets in ~/.claude/CLAUDE.md that you wouldn’t put in any other git repo. Auth tokens, API keys, etc. belong in environment variables, not in synced markdown.
  • ctrlrelay never reads, transforms, or transmits the contents itself beyond git push / git pull to the URL you configured. There is no telemetry on personalization.

Disabling

Remove the personalization: block from orchestrator.yaml and restart the poller. Existing symlinks remain on disk pointing into ~/.ctrlrelay/personalization. To revert a target back to a real file, copy through the symlink first (cp ~/.claude/CLAUDE.md /tmp/x && rm ~/.claude/CLAUDE.md && mv /tmp/x ~/.claude/CLAUDE.md). The checkout itself can be deleted once nothing points into it.