BoB Backup and Recovery

How BoB State Is Protected

The BoB source repo (BOB_SOURCE, default ~/projects/bigbrain) is hosted on GitHub (paulirv/bigbrain). All critical state is version-controlled and deployed to ~/.claude/ (BOB_HOME) at runtime:

• Skills, commands, agents — skills/, commands/, agents/, registry/
• Provision manifests — provisions/*.json (one per project) — operator data that belongs in your separate operator repo (#2270); until bob operator migrate --apply moves them, the legacy copies in BOB_SOURCE are still read
• Scripts and binaries — scripts/, bin/
• Shared settings — settings.json
• Templates and hooks — templates/, hooks/
• Documentation — docs/, runbooks/

What Is NOT Backed Up (By Design)

These are machine-specific or transient and are gitignored:

Item	Why	Recovery
settings.local.json	Machine-specific (automation level, RDB)	Re-set via /automation and /rdb
.mcp.json	Machine-specific MCP server paths	Re-configure MCP servers
CLAUDE.local.md	Machine-specific overrides	Re-create if needed
projects/	Claude Code session metadata	Regenerated automatically
history.jsonl	Conversation history	Not recoverable (ephemeral)
token-usage.jsonl	Token usage logs	Not recoverable (analytics only)
sessions/, remote/	Runtime state	Regenerated on use
.credentials.json	Sensitive auth tokens	Re-authenticate

Recovery Procedure

Terminal only. Every command in this guide is a terminal command, not a slash command — recovery runs from a shell, often on a fresh machine before any Claude Code session exists, so there is nothing to type /-commands into. The one exception worth knowing: where bob provision re-provisions a project below, the in-session equivalent is /provision — but it presupposes a working session, which recovery is what restores.

Full Recovery (Fresh Machine or Total Loss)

Terminal:

# 1. Clone the BoB source repo
git clone git@github.com:paulirv/bigbrain.git ~/projects/bigbrain
# ...and your operator repo, if you have one (manifests, machines.json — #2270);
# ~/projects/bob-operator is a default the resolver checks
git clone <your-operator-repo-url> ~/projects/bob-operator

# 2. Set environment variables (in ~/.zshrc)
export BOB_HOME="$HOME/.claude"
export BOB_SOURCE="$HOME/projects/bigbrain"

# 3. Deploy to ~/.claude/ and install CLI aliases
bash ~/projects/bigbrain/scripts/deploy.sh
bash ~/projects/bigbrain/scripts/bob-install.sh
source ~/.zshrc

# 4. Set machine-specific config
# (automation level, RDB, etc. — these are interactive)

# 5. Re-provision all projects
# For each project directory:
cd ~/Sites/project-name
bob init                          # Initialize global tooling symlinks
bob provision                       # Re-apply provision manifest

Automated Recovery

Use the cdr command (claude disaster recovery) to automate steps 1, 3 and 5 (cdr recover-global clones or pulls, reinstalls the shell line and re-provisions — it does not run deploy.sh). cdr is terminal only — it has no slash form:

Terminal:

cdr status                   # Show current tooling and warp-drive state
cdr check                    # Health check — verify critical files exist
cdr recover [project]        # Recover a project: fetch + re-run bob init -y
cdr reprovision              # Re-provision ALL known projects from manifests
cdr recover-global           # Full recovery: clone/pull + bob-install + check + reprovision
cdr reset [project]          # Emergency: remove warp-drive state file

The cdr alias is installed by bob-install.sh and points to scripts/lib/cdr.sh.

Partial Recovery (Corrupted Files)

If specific files are corrupted but the source repo is intact:

Terminal:

# In the source repo (BOB_SOURCE)
cd ~/projects/bigbrain

# Reset corrupted files from remote
git fetch origin master
git checkout origin/master -- path/to/corrupted/file

# Or reset everything to remote state
git reset --hard origin/master

# Re-deploy to runtime
bash scripts/deploy.sh

Re-Provisioning a Single Project

Terminal:

cd ~/Sites/project-name
bob init                          # Re-link global items
bob provision                       # Re-apply project manifest

The bob provision step has an in-session equivalent — /provision — once a Claude Code session is running; bob init is terminal only.

Prevention

1. Commit frequently — All changes to skills, commands, agents, provisions should be committed in BOB_SOURCE
2. Push to remote — After committing, push to GitHub: cd ~/projects/bigbrain && git push
3. Deploy after changes — Run scripts/deploy.sh to sync to ~/.claude/
4. Health check — Run cdr check periodically or let the session-start check catch issues
5. Don't manually edit — Use BoB CLI commands (bob init, bob provision, bob promote, bob link) which keep state consistent