backup-recovery

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)
• 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

Full Recovery (Fresh Machine or Total Loss)

# 1. Clone the BoB source repo
git clone git@github.com:paulirv/bigbrain.git ~/projects/bigbrain
 
# 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
cdi                          # Initialize global tooling symlinks
cdprov                       # Re-apply provision manifest

Automated Recovery

Use the cdr command (claude disaster recovery) to automate steps 1-4:

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 cdi
cdr reprovision              # Re-provision ALL known projects from manifests
cdr recover-global           # Full recovery: clone/pull + aliases + 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:

# 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

cd ~/Sites/project-name
cdi                          # Re-link global items
cdprov                       # Re-apply project manifest

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 (cdi, cdprov, cdp, cdl) which keep state consistent