New Machine Setup Guide

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

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/bin:$BOB_SOURCE/bin:$PATH"   # ~/bin for cdi/cdb/cdp/cdl/cdg/cds; BOB_SOURCE/bin for warp/cdfork/dev-up/dev-health

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/

Step 4: Install CLI Wrapper and Aliases

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

This installs the claude wrapper function (supports -a1, -a2, -a3, -rdb flags) and aliases (cdprov, cdr, cdfork).

Step 5: Set Up CLI Commands

Create ~/bin if it doesn’t exist, then symlink the CLI tools:

mkdir -p ~/bin

# Replace $BOB_SOURCE with your actual path if the env var isn't set
ln -sf "$BOB_SOURCE/claude-init.sh" ~/bin/cdi
ln -sf "$BOB_SOURCE/claude-dashboard.sh" ~/bin/cdb
ln -sf "$BOB_SOURCE/claude-promote.sh" ~/bin/cdp
ln -sf "$BOB_SOURCE/claude-link.sh" ~/bin/cdl
ln -sf "$BOB_SOURCE/scripts/generate-dashboard.js" ~/bin/cdg
ln -sf "$BOB_SOURCE/scripts/dashboard-server.js" ~/bin/cds

Step 6: Verify Installation

# 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
cdi    # Creates .claude/ with symlinks to BOB_SOURCE

Project symlinks point to BOB_SOURCE (the source repo), not ~/.claude/.

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 ~/bin is in PATH
echo $PATH | tr ':' '\n' | grep bin
# Re-create symlink
ln -sf ~/projects/bigbrain/claude-dashboard.sh ~/bin/cdb

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