New Machine Setup Guide

Step-by-step guide to get BoB running on a fresh machine.

Terminal only — runs before BoB/Claude is available. Every command in this guide is a shell command. New-machine setup bootstraps BoB before any Claude Code session exists, so none of these steps has a slash-command equivalent. Run them from a terminal.

Prerequisites

Dependency	Minimum Version	Install
macOS or Linux	macOS 13+ / Ubuntu 22+	—
Git	2.30+	brew install git or apt install git
Node.js	18+	brew install node or nvm
jq	1.6+	brew install jq or apt install jq
Claude Code CLI	Latest	npm install -g @anthropic-ai/claude-code

Step 1: Clone BoB

Clone the BoB source repo to a dedicated projects directory (not ~/.claude/):

git clone git@github.com:paulirv/bigbrain.git ~/projects/bigbrain

Step 2: Set Environment Variables

Add to ~/.zshrc or ~/.bashrc:

export BOB_HOME="$HOME/.claude"                 # Runtime directory (Claude Code reads this)
export BOB_SOURCE="$HOME/projects/bigbrain"     # Source repo
export PATH="$HOME/.claude/bin:$PATH"           # Deployed entrypoints (cdi, cdb, warp, dev-up, …)

(The bob-shell.zsh snippet installed in Step 4 also guards this PATH entry, so the export is belt-and-braces.)

Then reload: source ~/.zshrc

Step 3: Initial Deploy

Deploy from the source repo to ~/.claude/:

# If ~/.claude/ already exists from a previous installation:
bash ~/projects/bigbrain/scripts/deploy.sh --first-run

# For a fresh machine where ~/.claude/ doesn't exist yet:
bash ~/projects/bigbrain/scripts/deploy.sh

The deploy script:

• Syncs skills, commands, agents, hooks, scripts, templates, registry to ~/.claude/
• Preserves machine-specific files (settings.json, settings.local.json, CLAUDE.local.md)
• On --first-run: removes legacy .git/ and .claude/ dirs from ~/.claude/, and retires legacy ~/bin cd* shims via scripts/migrate-cd-entrypoints.sh (#1194)

BOB_HOME is never a clone. ~/.claude/ is pure deploy output plus the protected machine-specific files — first-run setup is deploy.sh --first-run, never git clone. A .git/ inside ~/.claude/ is a stale bootstrap fossil that tooling can mistake for a source checkout (#1476); routine deploys warn about it and the fleet snapshot flags it as bob_home_git_fossil (#1477).

Step 4: Install Shell Integration

bash ~/projects/bigbrain/scripts/bob-install.sh
source ~/.zshrc

This adds one guarded line to ~/.zshrc (#1195):

[ -f "$HOME/.claude/bin/bob-shell.zsh" ] && source "$HOME/.claude/bin/bob-shell.zsh"

The sourced snippet — deployed and version-controlled, never hand-edited — defines the claude() wrapper (-a1…-a4, -rdb flags), the cdr alias, and a guarded PATH prepend for ~/.claude/bin. It deliberately defines no aliases for cdprov/cdfork/cdproj: those are bin/ entrypoints resolved via PATH, and an alias would shadow them.

Migrating an older machine: if your ~/.zshrc carries the legacy inline wrapper/alias block (fenced by # --- BoB Claude Wrapper ---), just re-run bob-install.sh — it replaces the whole fenced block with the source line. Inline definitions outside the fence must be removed by hand.

Step 5: Put the Deployed Entrypoints on PATH

No per-command symlinks are needed (#1194): the deployed ~/.claude/bin/ directory IS the command surface (cdi, cdb, cdp, cdl, cdg, cds, cdprov, warp, dev-up, …). Just make sure it's on PATH:

# In ~/.zshrc (bob-install.sh adds this on new machines)
export PATH="$HOME/.claude/bin:$PATH"

Migrating an older machine: if hand-made ~/bin shims from an earlier setup exist, they shadow ~/.claude/bin (~/bin usually precedes it on PATH). deploy.sh --first-run retires them automatically, or run the migration directly:

bash "$BOB_SOURCE/scripts/migrate-cd-entrypoints.sh" --dry-run   # preview
bash "$BOB_SOURCE/scripts/migrate-cd-entrypoints.sh"             # converge

It backs up every shim it removes to ~/bin/.bob-shim-backup/, refuses to touch files that aren't recognizably BoB's, and is safe to re-run. make check warns if a shadowing shim reappears.

Step 6: Verify Installation

The one-command answer is bob doctor (make check-host from the source checkout, #1921): it grades every deploy-managed surface, every symlink, the toolchain and the settings.json hook wiring on this machine, and names the fix for anything behind — Converged means the machine is what deploy.sh would produce.

bob doctor            # exit 0 converged · 1 drift (output names the fix) · 2 error

Or piece by piece:

# Check deployed runtime
ls ~/.claude/skills/ ~/.claude/commands/ ~/.claude/hooks/

# Check source repo
ls ~/projects/bigbrain/scripts/ ~/projects/bigbrain/registry/

# Check CLI tools work
cdb --global-only

# Check dependencies
node --version   # Should be 18+
jq --version     # Should be 1.6+

Step 7: Clone Project Repos

Clone each project you work with, then initialize with BoB tooling:

git clone git@github.com:example/bodmail.git ~/Sites/bodmail
cd ~/Sites/bodmail
bob ready    # cdi -y → cdprov refresh → labels → ports → manifests, then READY / NOT READY

bob ready is idempotent and never prompts — re-run it any time; a NOT READY verdict names the fix per blocker (see bob ready). cdi alone still works, but it is only the first of the five steps.

Step 8: Machine-Specific Overrides (Optional)

cat > ~/.claude/CLAUDE.local.md << 'EOF'
# Machine: (your machine name)

- Projects directory: ~/Sites/ (or ~/Work/, etc.)
- Any machine-specific notes here
EOF

This file is gitignored and protected by deploy.sh.

Verification Checklist

• [ ] echo $BOB_SOURCE shows ~/projects/bigbrain
• [ ] cdb shows global tooling inventory
• [ ] cdi is available (which cdi)
• [ ] Opening Claude Code in any linked project loads BoB's CLAUDE.md
• [ ] Skills are available (start a Claude session, type /journal)
• [ ] Hooks fire (try editing a file on main branch -- should be blocked)

Updating BoB

Pull the latest source, then re-deploy:

cd ~/projects/bigbrain && git pull
bash scripts/deploy.sh
make check

Then re-provision active projects from their manifests:

cdr reprovision    # disaster-recovery CLI: re-applies every project's manifest

For a single project, cd <project> && cdprov --refresh is enough.

Troubleshooting

Symlinks are broken after clone:

# In the project directory:
cdi    # Re-creates all symlinks from BOB_SOURCE

cdb command not found:

# Check ~/.claude/bin is on PATH (the deployed entrypoints live there)
echo $PATH | tr ':' '\n' | grep claude
# If missing, add to ~/.zshrc:
export PATH="$HOME/.claude/bin:$PATH"
# Then redeploy if ~/.claude/bin/cdb itself is absent:
bash ~/projects/bigbrain/scripts/deploy.sh

Hooks not firing: Check that the project's .claude/settings.json references hook paths correctly. Hooks should point to .claude/hooks/*.sh (relative to project root), and those should be symlinks to $BOB_SOURCE/hooks/.

Skills not loading: Skills auto-load from ~/.claude/skills/. If they're missing, re-deploy:

bash ~/projects/bigbrain/scripts/deploy.sh