git-backup

Extra message: $ARGUMENTS

Requires the kit's scripts installed at ~/.claude/scripts/ (see SETUP.md). The repo URL lives in ~/.claude's git remote (origin), not in this file — keep it private; even with the whitelist, your config/memory is yours.

Pick a mode first

• "back up / snapshot / DR backup" -> the Save steps below.
• "restore / recover" -> jump to the Restore section at the bottom.

Goal

Snapshot the whole ~/.claude (a git work tree whose origin is your PRIVATE config repo) for full recovery after a machine failure. Take everything at once — do not cherry-pick; the whitelist .gitignore already keeps secrets out.

Save (one entry point — don't hand-compose add/commit/push)

Why one script: the manual add -> commit -> push -> verify chain kept turning into hand-composed compound commands, which is exactly where mistakes (and, in Claude Code, permission-prompt noise) creep in. The unattended SessionEnd hook already runs a deterministic script — manual saves go through the same single entry.

1. Run (pass $ARGUMENTS as -Note if present; otherwise omit -Note entirely):

   pwsh -NoProfile -File ~/.claude/scripts/auto-backup.ps1 -Note "<$ARGUMENTS>"

   The script does, in order (do not re-implement these steps by hand — one entry point, one implementation):
   • snapshots machine config living outside ~/.claude into profile/ (your PowerShell profile etc. — extend $Sources in snapshot-machine-config.ps1)
   • if you have your own work staged, it skips the snapshot rather than absorb it (SKIP snapshot: user has staged work — pending commits still push)
   • git add -A (safe: the whitelist .gitignore excludes credentials/history/ sessions/caches/plugins by construction)
   • fail-CLOSED secret scan covering everything a push would publish: the staged snapshot before commit AND every not-yet-pushed commit before push (so a secret committed by hand still cannot leave). On a hit it does NOT push and returns an ABORT: line naming rule@file (never the secret itself); relay that line to the user verbatim and stop. Audited false positives go in .lifeboat-allowlist.txt (one regex per line, matched against <ruleId> <path>).
   • skips the commit when the tree is clean, but still pushes pending commits left by an earlier failed push (OK: pushed N pending commit(s))
   • concurrent sessions are serialized by a mutex (SKIP: lock busy means another session is mid-git — not an error, the next trigger retries)
2. Verify (report evidence, not vibes): the commit hash, and ## main...origin/main with no ahead/behind:

   cd ~/.claude && git status -sb && git log -1 --oneline

Rules

• No destructive git: never reset --hard / push --force / clean -f. This backup is append-only (add -> commit -> push).
• If push is rejected as non-fast-forward, do NOT force. Stop and report; reconcile manually.

Restore — get your structure back on a dead / new machine

Preconditions:

• The repo is PRIVATE -> you must be authenticated to clone. Check gh auth status (logged in, token scope includes repo). If not, ask the USER to run gh auth login in a browser and stop. Never handle tokens for them; auth is per-machine and is intentionally NOT in the backup.
• Viewing the repo web page is not enough — restore is only via an authenticated git clone.
• ~/.claude usually already has content -> you cannot clone directly into a non-empty dir. Use the non-destructive steps below.

Steps (non-destructive, no destructive git):

1. Auth check: gh auth status (if not logged in, ask the user to gh auth login and stop).
2. Clone somewhere else (do NOT touch ~/.claude):

   git clone <PRIVATE_BACKUP_REPO_URL> ~/_claude-restore

3. Decide how to reconcile with any existing ~/.claude (irreversible -> confirm with the user):
   • New / near-empty machine -> rename existing aside (~/.claude -> ~/.claude.bak-YYYYMMDD), then move the clone into place. Most faithful (an exact copy of the repo).
   • Keep existing, overlay -> copy the clone's contents excluding .git (rsync -a --exclude='.git' ~/_claude-restore/ ~/.claude/ on macOS/Linux; robocopy "$HOME\_claude-restore" "$HOME\.claude" /E /XD .git on Windows). Copying .git into a directory that already has one corrupts the repo. Then reconnect git as its own step: if ~/.claude has no repo, move ~/_claude-restore/.git in; if it already is one, git fetch and reconcile instead (no resets).
4. Re-resolve machine-specific values. Old absolute paths (drive letters, usernames, install locations) are invalid on the new machine. Fix settings.json and anything under **/memory/ that references old paths.
5. Put the outside-the-repo files back. profile/manifest.json ({schemaVersion, entries:[{file, source}]}) records, for every snapshot in profile/, the absolute path it came from (source). Copy each file back — but inspect any existing file at the destination first (a fresh machine may already have its own profile; merge by hand, don't blind-overwrite). Paths inside these files need the same re-resolution as step 4.
6. Restart Claude Code (settings / skills / hooks load at startup).
7. Cleanup: remove ~/_claude-restore once verified (keep the .bak until the user confirms).

Also needed after restore (excluded from backup by design): gh auth login; your git identity (~/.gitconfig lives outside ~/.claude, so git config --global user.name / user.email are gone — the very first backup commit on the new machine fails with "Author identity unknown" until you set them); plus any local API keys / external tool setup. These are intentionally not tracked.