rdfitted/backup

Backup (Kopia)

Primary backup workflow. Handles setup (first-time repo init) and run (snapshot the configured sources to the connected external drive).

For verify / maintain / mirror / restore / top-up operations, use the backup-ops skill instead.

Modes

The user may say:

• "set up backups" / "initialize backup" / "first-time setup" → setup
• "run the backup" / "back up now" / "snapshot" → run (default)
• "what's my backup status" / "when did I last back up" → status

If unclear, default to run if a config exists, otherwise setup.

Prerequisites

1. Kopia must be installed. Check with kopia --version. If missing:

   • Recommend the user install KopiaUI from https://kopia.io/docs/installation/ (gives both CLI + GUI tray app)
   • Or via winget: winget install --id Kopia.KopiaUI (bundles GUI + CLI; CLI binary lives at %LOCALAPPDATA%\Programs\KopiaUI\resources\server\kopia.exe and must be added to user PATH manually). For CLI-only, use Kopia.KopiaCLI.
   • Do NOT silently install — ask first.

2. Config file: ~/.claude/backup-config.json (see template at end of this file). If missing, run setup first.

3. Backup drive must be plugged in. Detection is by volume label, not drive letter — letters are not stable.

Setup mode (first run)

1. Confirm Kopia is installed.
2. Ask the user for the volume label of the backup drive (e.g. "RyanBackup"). Walk them through setting it:
   • Get-Volume to see current labels
   • If they want to rename: Set-Volume -DriveLetter X -NewFileSystemLabel "RyanBackup" (X = current letter)
3. Detect the drive's current letter via the label:

   $vol = Get-Volume -FileSystemLabel "RyanBackup" -ErrorAction Stop
   $drive = "$($vol.DriveLetter):"
   

4. Ask user for a repo password. Critical: tell them:
   • Store it in their password manager AND somewhere offline
   • There is no recovery — lost password = lost backups
   • Min 12 chars recommended
5. Create the repo:

   kopia repository create filesystem --path "$drive\KopiaRepo" --password "..."
   

   Use --persist-credentials so future connects don't need the password interactively. Kopia stores it in Windows Credential Manager.
6. Write ~/.claude/backup-config.json (see template below) with the drive label and source list.
7. Confirm with a dry-run: list what would be backed up without actually snapshotting.

Run mode (the common path)

1. Load config from ~/.claude/backup-config.json. If missing, route to setup.
2. Detect drive by label. If not mounted, print a clear error and stop — do not proceed.
3. Connect to repo:

   kopia repository connect filesystem --path "<drive>:\KopiaRepo"
   

   (Credentials should be persisted; if not, prompt user.)
4. Snapshot each source path from the config:

   kopia snapshot create "<path>" --description "auto-backup <ISO timestamp>"
   

   Run snapshots sequentially, not in parallel — Kopia handles its own parallelism internally and concurrent snapshots can lock the repo.
5. Log results to ~/.claude/backup-logs/<ISO date>.log:
   • Per-source: bytes added, files changed, duration, snapshot ID
   • Overall: total duration, repo size delta
6. Report to user:
   • Per-source summary (one line each)
   • Anything skipped because the path didn't exist
   • Recommend running /backup-ops verify after every Nth backup (e.g., weekly)

Status mode

1. kopia snapshot list --all --max-results 20 — show recent snapshots
2. kopia repository status — show repo size, last maintenance, etc.
3. Read latest log from ~/.claude/backup-logs/ and surface last-run timing
4. Flag any sources that haven't been snapshotted in >7 days

Default sources (used in setup)

Suggest these for the config — let the user accept/reject each:

High-value, low-volume (always include):

• C:\Users\USERNAME\.claude — Claude Code config, hooks, commands, client memory
• C:\Users\USERNAME\.ai-docs — global wiki + mainbrain
• C:\Users\USERNAME\.ssh — SSH keys (critical, encrypted in repo)
• C:\Users\USERNAME\.aws — AWS credentials
• C:\Users\USERNAME\.azure — Azure credentials
• C:\Users\USERNAME\.gemini — Gemini config (shared by gemini + antigravity CLIs)
• C:\Users\USERNAME\.codex — Codex config
• C:\Users\USERNAME\.cursor — Cursor config
• C:\Users\USERNAME\.config — generic dotconfig
• C:\Users\USERNAME\.gitconfig — git config (single file — Kopia handles files fine)
• C:\Users\USERNAME\CLAUDE.md — personal persona
• C:\Users\USERNAME\AGENTS.md, GEMINI.md — other persona files
• C:\Users\USERNAME\.claude.json, .claude.json.backup — active Claude config

Medium-volume:

• C:\Users\USERNAME\Documents
• C:\Users\USERNAME\Desktop
• C:\Users\USERNAME\plans
• C:\Users\USERNAME\scripts
• C:\Users\USERNAME\bin

Large but worth it (project work):

• C:\Users\USERNAME\Code Projects
• C:\Users\USERNAME\CodeProjects (duplicate of above? — ask user)
• D:\Code Projects

Audit and ask the user:

• C:\Users\USERNAME\dev, app, src, ai, archon, big-3-super-agent, ccflare, goose, mcp-replicate, nanoclaw — top-level project-ish dirs at home root
• C:\Users\USERNAME\Proposal Creation Platform, Applegate — looked work-related

Already cloud-synced (probably skip but ask):

• Dropbox, OneDrive, Creative Cloud Files...

Credential files at home root (sensitive — include but flag):

• .cli-m365-*.json (M365 CLI tokens, per memory notes)
• .replitcli.json, .npmrc, .boto

Exclusions (apply to every source)

Kopia uses .kopiaignore files and policy-based excludes. Configure in setup via:

kopia policy set --global \
  --add-ignore "node_modules" \
  --add-ignore ".venv" \
  --add-ignore "__pycache__" \
  --add-ignore ".pytest_cache" \
  --add-ignore "dist" \
  --add-ignore "build" \
  --add-ignore ".next" \
  --add-ignore ".turbo" \
  --add-ignore ".cache" \
  --add-ignore "*.pyc" \
  --add-ignore ".DS_Store" \
  --add-ignore "Thumbs.db" \
  --add-ignore "*.log" \
  --add-ignore "tmp" \
  --add-ignore "*.tmp"

Never back up at root:

• ~/.cache, ~/.npm, ~/.pnpm, ~/.bun, ~/.cargo, ~/.rustup, ~/.m2, ~/.gradle, ~/.nuget, ~/.electron-gyp, ~/.local, ~/npm-cache
• ~/.docker, ~/.minikube, ~/.skaffold
• ~/.playwright-mcp, ~/.browser-driver-manager, ~/.wdm
• ~/.pytest_cache, ~/IntelGraphicsProfiles
• ~/tmp, ~/scratch, ~/logs
• ~/tmpclaude-* files
• ~/node_modules (yes, there's one at home root — exclude it)

Retention policy (set at setup)

kopia policy set --global \
  --keep-latest 10 \
  --keep-hourly 24 \
  --keep-daily 14 \
  --keep-weekly 8 \
  --keep-monthly 12 \
  --keep-annual 3

Config file template (~/.claude/backup-config.json)

{
  "tool": "kopia",
  "repo": {
    "type": "filesystem",
    "drive_label": "RyanBackup",
    "repo_subdir": "KopiaRepo"
  },
  "secondary": {
    "enabled": false,
    "type": "s3",
    "bucket": "",
    "endpoint": "",
    "drive_label": ""
  },
  "sources": [
    "C:\\Users\\RDuff\\.claude",
    "C:\\Users\\RDuff\\.ai-docs",
    "C:\\Users\\RDuff\\.ssh",
    "C:\\Users\\RDuff\\.aws",
    "C:\\Users\\RDuff\\.azure",
    "C:\\Users\\RDuff\\.gemini",
    "C:\\Users\\RDuff\\.codex",
    "C:\\Users\\RDuff\\.config",
    "C:\\Users\\RDuff\\.gitconfig",
    "C:\\Users\\RDuff\\CLAUDE.md",
    "C:\\Users\\RDuff\\.claude.json",
    "C:\\Users\\RDuff\\Documents",
    "C:\\Users\\RDuff\\Desktop",
    "C:\\Users\\RDuff\\plans",
    "C:\\Users\\RDuff\\scripts",
    "C:\\Users\\RDuff\\Code Projects",
    "D:\\Code Projects"
  ],
  "hot_sources_for_top_up": [
    "C:\\Users\\RDuff\\.claude",
    "C:\\Users\\RDuff\\.ai-docs",
    "C:\\Users\\RDuff\\plans"
  ],
  "restore_mappings": {
    "source_paths": []
  },
  "log_dir": "C:\\Users\\RDuff\\.claude\\backup-logs"
}

Optional: restore_mappings for cross-machine restores

Consumed by the restore skill (/restore wikis) to handle source/target path differences and project name drift when restoring from a backup created on a different machine. Leave source_paths: [] (the default) for same-machine restores or when source and target naming are identical.

Example for a target machine (ryanlaptop) restoring from a source machine (mainframe) that named projects differently:

"restore_mappings": {
  "source_paths": [
    {
      "source": "D:\\Code Projects",
      "target": "C:\\Users\\RDuff\\Code Projects",
      "project_name_map": {
        "GVB ERP":                  "gvb",
        "Ultra Building Solutions": "ultrabuildingsolutions",
        "TOG - ERP":                "tog-erp",
        "the og main brain":        "ogmainbrain",
        "TOG PM Assistant":         "ogpmbrain"
      }
    }
  ]
}

See skills/restore/SKILL.md § "Cross-machine name mapping" for the full semantics. This block is only read by restore; backup ignores it.

Hard rules

• Never run a backup without confirming the destination drive label matches. Drive letters lie.
• Never store the Kopia password in the config file or anywhere in plaintext on disk. Use Kopia's credential persistence (Windows Credential Manager).
• Never snapshot sources in parallel via concurrent CLI calls — Kopia's repo lock will reject them.
• Never delete or prune snapshots in this skill — that's backup-ops maintain.
• Always log to ~/.claude/backup-logs/ with ISO-date filenames.
• Always report which sources were skipped because the path didn't exist (could be a typo in config or an unmounted drive).