Run the Latest BoB

A project does not have its own copy of BoB. Its .claude/ links point into this machine's BOB_HOME (~/.claude), so a project runs whatever BoB the machine last deployed. To keep a project current, you update the machine and then refresh what the project and its running processes loaded.

Terminal only. bob update refuses while a Claude Code session is running on the machine, so run these steps from a plain shell.

1. See which BoB this machine runs

bob doctor

Look for the version line near the end:

  INFO  version: 1.275.0 (v1.275.0) [stable] deployed 2026-09-21T19:47:42Z from 9fa178d

It shows the version, the tag, the channel (stable, nightly, or checkout for an untagged deploy), when it was deployed and the source commit. The same record is in ~/.claude/.bob-version.

2. Check whether a newer release exists

bob update --dry-run

This fetches tags and prints the tag it would move to, without writing anything. If the checkout is already at the newest tag, it says so:

bob update: checkout already at v1.275.0 (9fa178d4) on master — nothing to fast-forward; deploy still runs so BOB_HOME converges

To compare against the nightly channel instead, add --channel nightly.

3. Update the machine

Exit every Claude Code session on the machine first. Then run:

bob update                       # newest stable vX.Y.Z (the default)
bob update --channel nightly     # newest nightly-YYYY-MM-DD
bob update --to v1.275.0         # one exact tag

bob update fast-forwards the BoB source checkout to the tag, runs scripts/deploy.sh and then bob doctor. It exits 0 only when doctor reports Converged — this machine's BOB_HOME matches source.

On a machine declared bob_channel: stable or nightly (a laptop pinned to releases, #3171), bob update leaves the checkout alone. It fetches tags and deploys the channel's newest tag from its own worktree, and the version line in bob doctor then reads channel: stable vX.Y.Z (newest). See A machine pinned to a release channel.

It refuses (and changes nothing) when:

Exit	Cause	Fix
4	a Claude Code session or warp-drive run is live	nothing to run: the update is queued in ~/.claude/.deploy-pending, and BoB runs it when the last session ends (#3162). bob doctor shows update queued since … until then
3	the source checkout has tracked changes or is off its main branch	commit, stash or switch back, then re-run
1	doctor found drift after the deploy	follow the fix doctor names

Running it again is safe. On an up-to-date machine it re-deploys and re-checks.

4. Converge the project

From the project's root:

bob ready

This re-verifies the project's links against the new deploy and retargets any link to an item that the release renamed or retired. Its version step checks the project's pin (see step 6). It ends with READY — <project> is warp-drive-ready on this machine.

5. Restart what loaded the old version

A deploy changes files on disk. Processes that started before it keep running the old code until they restart:

• Claude Code sessions. Skills, commands and hook wiring are read when a session starts. Exit and start each session again.

• Dashboards. bob doctor flags any dashboard started before the current deploy:

  ! bigbrain :6952 tailnet (100.103.9.107) pid 514294 up 1d18h — started before the current deploy — Fix: bob dash serve --stop bigbrain

  Stop it, then start it again from the project's root with the same bind (drop --tailnet if it served on localhost):

  bob dash serve --stop bigbrain
  bob dash serve --tailnet

6. Optional: pin a project to a version

If a project must not change version when the machine does, pin the version in its dev.json:

{ "bob_version": "stable" }

The value is a channel (stable, nightly) or an exact tag (v1.275.0, nightly-2026-09-21). bob ready then blocks when the machine runs something else, and names the fix:

BLOCKED      version    BOB_HOME runs 1.273.0 (v1.273.0) [stable], project pins tag v1.270.0 — fix: bob update --to v1.270.0

With no pin, any deployed BoB is accepted.

Check it worked

bob doctor | tail -3
bob ready --dry-run | tail -1

Doctor's version line shows the tag from step 2 and ends with Converged, no dashboard is flagged, and the project reports READY.

See also

• Versioning Guide — Updating a machine: the full bob update sequence and its gates.
• Versioning Guide — Pinning a project
• bob ready — Steps
• Farm Tick: how the farm updates itself unattended.