BoB — Big ol' Brain

TL;DR. "BoB" (Big ol' Brain) is the name for this entire global Claude Code tooling framework — everything in BOB_SOURCE (skills, agents, commands, hooks, scripts, PM), deployed to ~/.claude/ (BOB_HOME).

Identity

BoB (Big ol' Brain) is the name for this global Claude Code tooling framework. Everything in the BoB source repo (BOB_SOURCE) — skills, agents, commands, hooks, templates, scripts, and project management — is BoB. It is deployed to ~/.claude/ (BOB_HOME) where Claude Code reads it at runtime.

When someone says "Bob", "BoB", "big brain", or "big ol' brain", they mean this framework and all projects linked to it.

What BoB Is

• The source repo (BOB_SOURCE, default ~/projects/bigbrain) and its deployed runtime (BOB_HOME, ~/.claude/)
• The symlink architecture that distributes tooling to projects
• The CLI tools: bob init, bob dash status, bob promote, bob link, bob provision
• The conventions, quality gates, and workflows enforced by hooks
• The institutional memory stored in GitHub Issues (decisions, lessons, session summaries)

What BoB Is Not

• BoB is not Claude itself — BoB is the framework Claude operates within
• BoB is not any single project — BoB serves all linked projects equally
• BoB is not a cloud service — everything runs locally

Aliases

All of these refer to the same thing:

Alias	Usage
Bob	Casual reference ("Bob, set up a new project")
BoB	Stylized abbreviation ("BoB framework")
big brain	Informal ("let big brain handle it")
big ol' brain	Full name, rarely used

Natural Language Examples

• "Bob, set up a new project" → run bob init to initialize with global tooling
• "Is Bob up to date?" → check git status of BOB_SOURCE and symlink health via bob dash status
• "What does Bob have for code review?" → describe the code-reviewer agent and code-expert skill
• "Bob needs a new skill" → create a directory in BOB_SOURCE/registry/skills/ (the universal skills/ is the minimal core), then deploy and provision it
• "Push this to Bob" → promote a local item to global via bob promote

Architecture Summary

BoB is a source repo (BOB_SOURCE) deployed to a runtime directory (BOB_HOME, ~/.claude/) and symlinked into each project's .claude/. The full source→runtime model — directory tree, component types, and what syncs how — is documented once in the handbook → The Big Picture.

Ownership Seam: BoB, Fleet, thefarm

BoB runs on three kinds of host and owns exactly one thing on each of them: BOB_HOME. The layer beneath it is owned per machine by a host provider, declared in machines.json (host_provider: {id, command}, #1925) — never discovered from PATH:

Layer	Owner	Declares	Reports as
BOB_HOME — deployed skills, scripts, hooks, registry, settings hook wiring; every project's .claude/ links	BoB (this repo), on every machine	deploy.sh, provisions/, machines.json (the last two are operator data, read from the operator repo — #2270)	bob doctor / make check-host (#1921), carried in every fleet snapshot as summary.host_drift — with or without a host provider
The laptop host — Homebrew bundle, iTerm2 profiles, repo checkouts, Tailscale/SSH reachability, and the laptop→farm relationship	Fleet (paulirv/fleet, ~/projects/fleet; vision: docs/vision.md there)	fleet manifest	fleet status --json → fleet-status/1, a profile of host-status/1
farm-01's OS and workloads — packages, the Actions runner, the bob workload that bootstraps BOB_HOME on Linux	thefarm (paulirv/thefarm, ~/projects/thefarm; vision: docs/vision.md there)	farm workloads	farm status --json → host-status/1

The seam is held together by one contract, owned here: schemas/host-status.schema.json (host-status/1). It is deployed to BOB_HOME/schemas/ on every machine, and both providers validate their output against it with node $BOB_HOME/scripts/fleet/host-status-validate.js. scripts/fleet/audit.js consumes either provider by contract, not by name: sections are provider-defined (brew/iterm2/repos/tailscale/bob_home from Fleet, apt/runner/docker/bob_home/… from thefarm), na: true is not-measured rather than drift, and the view "Host drift" table shows all three machines with columns drawn from whatever sections were reported. A declared provider whose command is missing is host.error in that machine's snapshot — never a failed snapshot, and never a reason summary.host_drift is absent.

Rules of the seam: BoB never probes Homebrew, iTerm2 or apt; Fleet and thefarm never write into BOB_HOME except by running deploy.sh; a bob_home section from either provider wraps BoB's own host check (bob doctor) so there is one definition of "BOB_HOME converged". "The fleet" (BoB's machine set, machines.json, scripts/fleet/*) and Fleet (the laptop host project) remain two different things.

A client farm is the same seam in a client's account, with one owner made explicit: the host provider owns the OS and workloads, BoB owns BOB_HOME, and the client's operator repo owns the declaration. The host provider's tooling and the client's farm data live apart (decision #4219). See Client Farms.

Cross-Machine Pattern

BoB is portable because the source repo is a git repo:

1. Clone the source repo to ~/projects/bigbrain
2. Set BOB_SOURCE and BOB_HOME env vars in ~/.zshrc
3. Deploy to ~/.claude/ via scripts/deploy.sh
4. Install dependencies (jq, Node.js 18+) and CLI aliases (scripts/bob-install.sh)
5. Clone project repos and run bob init in each to create symlinks
6. Create CLAUDE.local.md for any machine-specific overrides (gitignored)

See New Machine Setup for the full guide.