---
name: codex-backup-recovery
description: Create, validate, inspect, and restore a secret-free allowlisted backup of Codex, Claude Code, and shared Agent skills, memories, rules, commands, and automations. Use when a user wants a daily Agent workspace backup, a new-Mac migration rehearsal, disaster-recovery verification, or an audit of exactly what an Agent backup contains. Do not use as a full-disk backup or to copy credentials and login sessions.
---

# Codex Backup Recovery

Back up reusable Agent capabilities without bundling authentication files or an entire home directory. Treat the snapshot as private because memories and workflows can still contain personal context.

## Workflow

### 1. Confirm scope and destination

Explain that this covers the allowlist in [references/snapshot-contract.md](references/snapshot-contract.md), not applications, Keychain, OAuth sessions, runtimes, or full-disk data. Let the user choose a local or cloud-synced output directory.

Never add credentials, arbitrary home-directory paths, or a public upload step.

### 2. Create the snapshot

```bash
python3 scripts/backup_recovery.py create \
  --home "$HOME" \
  --output "$HOME/Backups/agent-workspace"
```

Report both the `.tar.gz` archive and its `.sha256` sidecar. Do not say the backup is valid merely because the files exist.

### 3. Validate it

```bash
python3 scripts/backup_recovery.py check \
  --snapshot "$HOME/Backups/agent-workspace/agent-environment-YYYYMMDD-HHMMSS.tar.gz"
```

Require a readable archive, safe member paths, allowed file types, and a matching checksum when the sidecar is present. Spot-check that no `auth.json`, session, log, cache, database, or symlink appears.

### 4. Rehearse restoration

Restore is a dry run by default:

```bash
python3 scripts/backup_recovery.py restore \
  --snapshot "/path/to/agent-environment-YYYYMMDD-HHMMSS.tar.gz" \
  --home "/path/to/test-home"
```

Review the destination list. The dry run must not create the destination directory.

### 5. Apply only after explicit confirmation

```bash
python3 scripts/backup_recovery.py restore \
  --snapshot "/path/to/agent-environment-YYYYMMDD-HHMMSS.tar.gz" \
  --home "$HOME" \
  --apply
```

After applying, open a few restored `SKILL.md` files and rerun the snapshot check. Re-authentication and application installation remain separate manual steps.

Existing destination files are refused by default. If the reviewed plan is intentionally replacing an existing Agent environment, obtain separate confirmation and add `--overwrite`; never use it as a convenience fallback after a collision.

## Safety boundaries

- Use the fixed allowlist; never turn this into an unrestricted home-directory archive.
- Do not add an `include secrets` option.
- Never publish a real snapshot, even when credential files are absent.
- Do not claim disaster recovery is complete until creation, checksum validation, dry run, and restored-file spot checks all pass.