TOOL enhance, feat: Add `diff`, `backup --user-only`, and `migrate --auto` for safer PAI release updates

[sauldataman]

Problem

Updating PAI to a new release currently requires manual effort and carries risk of losing user data.

1. The migrate command misses most user data

Running migrate on a backup only identifies:

• _-prefixed skills (most users don't use this convention)
• Settings identity fields
• MEMORY subdirectory names

It completely misses:

• PAI/USER/ content (TELOS, identity, contacts, security patterns)
• Non-prefixed custom skills, Packs installed after setup
• User-modified system files (tweaked hooks, skills)
• projects/ (Claude Code auto-memory), user knowledge bases, user-generated skills, installed Packs, plugins
• settings.json hook/statusLine customizations
• Claude Code generated data (file-history/, Plans/, tasks/, History/)

And it only produces a text report — it doesn't actually restore anything. Users must manually copy files from the backup.

2. No way to preview what a release update will change

Users run cp -r new-release/.claude ~/ blindly. There's no way to see which local files will be overwritten, which are unchanged, or which are new — until after it's done.

3. No automated restore after release update

After cp -r overwrites files, users must manually find their modifications in the backup directory and copy them back. This is error-prone and tedious, especially for users who have customized hooks, skills, or PAI/USER/ content.

Related: #893 (settings.json overwrite during update)

Proposed Solution

Three new capabilities added to the existing Tools/BackupRestore.ts. All existing commands (backup, restore, list, migrate) are completely unchanged.

1. diff --release <path> — Preview before updating

Compare every file in a release against the local ~/.claude/ using SHA-256 hashes:

bun Tools/BackupRestore.ts diff --release ./Releases/v4.1.0/.claude

Shows:

• New files — in the release but not locally (will be added)
• Unchanged — identical content (safe to overwrite)
• Conflicts — exist locally with different content (user modifications that will be lost)

Automatically excludes from conflict reporting:

• PAI/USER/*, MEMORY/* — always user data, always preserved separately
• settings.json — always preserved separately, handled by install.sh merge
• PAI-Install/* — always replaced by release
• CLAUDE.md — regenerated by BuildCLAUDE.ts

2. backup --user-only --release <path> — Smart backup

Back up only user data, using the release directory as reference:

bun Tools/BackupRestore.ts backup --user-only --release ./Releases/v4.1.0/.claude

Captures three categories:

1. Always-backup data — PAI/USER/*, MEMORY/*, settings.json, CLAUDE.md
2. Modified system files — files in the release that the user has changed (SHA-256 differs)
3. User-generated files — everything in ~/.claude/ that doesn't exist in the release (user-generated skills, installed Packs, knowledge bases, projects/ with Claude Code auto-memory, plugins, etc.)

Users can review the diff output first, then exclude specific conflict files they don't want to keep:

bun Tools/BackupRestore.ts backup --user-only --release ./Releases/v4.1.0/.claude \
  --exclude 'skills/SomeSkill/SKILL.md' \
  --exclude 'PAI/SomeDoc.md'

The existing full backup command is unchanged and remains the recommended safety net.

3. migrate --auto — Automated restore

After applying a new release (cp -r), restore user data from a user-only backup:

bun Tools/BackupRestore.ts migrate --auto --release ./Releases/v4.1.0/.claude

• Automatically finds the latest user-only backup (or specify --backup <path>)
• Restores all user files on top of the new release
• Skips CLAUDE.md (regenerated by BuildCLAUDE.ts in the next step)
• Restores settings.json so that install.sh's merge logic can read the user's existing config

Without --auto, migrate works exactly as before (text analysis report).

Complete Migration Flow

# 1. Full backup (safety net — required)
bun Tools/BackupRestore.ts backup --name "pre-v4.1"

# 2. Preview what the release will change
bun Tools/BackupRestore.ts diff --release ./Releases/v4.1.0/.claude

# 3. Smart backup of user data
bun Tools/BackupRestore.ts backup --user-only --release ./Releases/v4.1.0/.claude

# 4. Apply new release
cp -r ./Releases/v4.1.0/.claude ~/

# 5. Auto-restore user data
bun Tools/BackupRestore.ts migrate --auto --release ./Releases/v4.1.0/.claude

# 6. Merge settings (install.sh reads restored settings.json)
cd ~/.claude && bash install.sh

# 7. Rebuild CLAUDE.md
bun ~/.claude/PAI/Tools/BuildCLAUDE.ts

How It Works

The release directory itself serves as the reference — no manifest file needed.

diff compares each release file against the local copy using SHA-256:

• Not in local → new file
• Same hash → unchanged
• Different hash → conflict (user modified)

backup --user-only collects:

• Everything in PAI/USER/ and MEMORY/ (explicitly, regardless of release content)
• settings.json and CLAUDE.md (always)
• All local files not present in the release (user-generated)
• Release files where local hash differs (user modifications)

migrate --auto copies the backup contents back into ~/.claude/, skipping only CLAUDE.md which is regenerated by BuildCLAUDE.ts.

Scope of Changes

File	Change
Tools/BackupRestore.ts	Add diff, backup --user-only, migrate --auto

All existing commands (backup, restore, list, migrate) are unchanged. No new files, no changes to release structure. Usage documentation is included in the tool's built-in help (bun BackupRestore.ts).

Future Work

• PR 2: Integrate migration flow into install.sh wizard — detect existing user-only backups and offer to restore during installation
• migrate --auto --dry-run to preview what would be restored
• Interactive conflict resolution (per-file keep/overwrite choice)

[danielmiessler]

Hey @sauldataman, thanks for raising this, and sorry it sat for a while.

We're changing how LifeOS ships. Instead of cloning a full ~/.claude directory and running it as a complete system, LifeOS is becoming a skill you install through an agentic installer. The installer hands integration to your own AI, which reads your actual machine (your OS, your paths, your harness) and wires the hooks and system prompt in where they belong.

That's aimed right at what you hit here. The old "one directory, one layout, hope it matches your setup" approach is exactly what broke for so many people, and the new model should handle it far better because your AI does the integration per machine instead of us guessing.

So we're closing this in prep for that release. If it still bites you once the skill-based version is out, reopen or file a fresh one and we'll jump on it. Appreciate you taking the time.