rdfitted/backup-ops

Backup Operations

Secondary operations on the Kopia repository created by the backup skill. Reads ~/.claude/backup-config.json for all settings.

Modes

Match the user's request to one of these. If ambiguous, ask which one.

| User says... | Mode | |---|---| | "verify backups", "check integrity", "are my backups good" | verify | | "prune snapshots", "clean up old backups", "run maintenance" | maintain | | "mirror to cloud", "copy to second drive", "set up offsite" | mirror | | "restore X", "I lost a file", "browse snapshots", "get back the version from yesterday" | restore | | "quick backup", "top up", "snapshot just .claude", "incremental" | top-up |

Prerequisites (all modes)

1. ~/.claude/backup-config.json must exist. If not, route to the backup skill's setup mode.
2. The primary backup drive must be mounted (detected by volume label from config). Exception: mirror writing to a cloud destination does not need the primary drive, but reading from the source repo does.
3. Repo must already be connected (kopia repository status returns successfully). If not, run kopia repository connect filesystem --path ... first using the config's drive label resolution.

Verify mode

Goal: confirm the repo's content is intact and readable. Catches bit rot, partial writes, drive corruption.

# Full verify of recent snapshots (slow but thorough)
kopia snapshot verify --verify-files-percent=10

# Or for a complete check (long-running, use sparingly):
kopia snapshot verify --verify-files-percent=100

Defaults:

• Run with --verify-files-percent=10 by default — samples 10% of file content per run
• Recommend a --verify-files-percent=100 run quarterly
• Report any errors immediately and stop; do not try to "fix" — surface to user

If the user asks for a quick check, use kopia repository status instead — that's metadata-only and fast.

Maintain mode

Goal: apply retention policy, compact the repo, garbage-collect orphaned blobs.

# Full maintenance (compacts indexes, drops expired snapshots, GCs unreferenced content)
kopia maintenance run --full

Notes:

• Kopia runs quick maintenance automatically on every snapshot. Full maintenance is what reclaims space.
• Default schedule: weekly or after every ~50 snapshots.
• Before running, show the user the current retention policy and ask if they want to adjust:

  kopia policy show --global
  

• After running, report bytes reclaimed and snapshots dropped.

Confirm with the user before running if any snapshot is about to be dropped — this is destructive in the sense that those versions are gone.

Mirror mode

Goal: replicate the primary repo to a second destination for 3-2-1 backup.

Kopia supports several remote types. Ask user which they want:

• Second external drive — filesystem type, different label
• S3-compatible (AWS S3, Backblaze B2, Wasabi, Cloudflare R2) — s3 type
• Azure Blob, GCS, SFTP — also supported

Pattern: replicate via kopia repository sync-to

# Example: mirror to S3
kopia repository sync-to s3 \
  --bucket "my-backup-mirror" \
  --endpoint "s3.amazonaws.com" \
  --access-key "..." --secret-access-key "..."

For a second filesystem destination:

kopia repository sync-to filesystem --path "<second-drive>:\KopiaMirror"

Update secondary section of backup-config.json with the chosen destination so future mirror runs are non-interactive.

Credentials: write to Windows Credential Manager via Kopia's persist flag — do NOT put cloud keys in the config file. If the user pastes a key into chat, warn them and recommend rotating it after setup since it's now in conversation history.

Restore mode

Goal: get specific files or folders back.

Interactive flow

1. Show recent snapshots for the source the user named:

   kopia snapshot list <source-path> --max-results 20
   

2. Ask user which snapshot (by date/ID) and what to restore.
3. Two restore patterns — ask which:
   • Mount as a virtual filesystem (best for browsing):

     kopia mount <snapshot-id> Z:
     

     Then user can drag files in Explorer. Unmount with kopia mount unmount Z:.
   • Direct restore (best for known paths):

     kopia snapshot restore <snapshot-id> "C:\restore-target"
     

4. Default restore target is NOT the original path — restore to a sibling folder (e.g. <original>-restored-<date>) and let the user move files manually. Never silently overwrite live files.

Quick file lookup ("what was in X yesterday")

# Find a file across snapshots
kopia snapshot list <source-path>
kopia content show <object-id-from-listing>

Top-up mode

Goal: fast incremental snapshot of high-churn directories only. Use between full backup runs.

1. Read hot_sources_for_top_up from config.
2. Snapshot each, sequentially:

   kopia snapshot create "<hot-path>" --description "top-up <ISO timestamp>"
   

3. Log to ~/.claude/backup-logs/topup-<date>.log.
4. Do NOT run maintenance after a top-up — that's a separate operation.

Suggested hot sources (set during backup setup):

• ~/.claude (config changes constantly)
• ~/.ai-docs (wiki updates)
• ~/plans
• Active project the user is in (if cwd is under a known source)

If the user says "top-up the X project", scope to just that path even if it's not in hot_sources_for_top_up.

Cross-cutting rules

• Never modify the primary backup workflow from this skill. If config needs changing, surface that to the user.
• Never run maintain without explicit user confirmation when snapshots will be dropped.
• Always verify the repo is connected before any operation: kopia repository status exits non-zero if not.
• Always log destructive operations (maintain, restore-over-live, mirror-credentials-changed) to ~/.claude/backup-logs/.
• For credentials: if the user pastes an S3 key, cloud token, or any secret into the conversation to configure mirror, recommend rotation after setup. Conversation history persists.
• Restore safety: never overwrite the source path by default. Always restore to a new location and let the user copy back.

Cross-references

• Primary backup workflow: backup skill
• Config schema: see template in backup/SKILL.md
• Wiki: if patterns from this skill prove useful long-term, curate via /curate-learnings → ~/.ai-docs/wiki/practices/