Upgrade and uninstall

xcb updates only to verified releases: an exact archive for your platform with a matching SHA-256 checksum, never a branch or an unverified build.

Upgrade

xcb update check        # is a newer release available?
xcb upgrade             # install the latest verified release
xcb upgrade <version>   # install a specific release

xcb upgrade reruns the installer that install-native.sh recorded, so it needs an install made with that script. If you built from source, update the checkout and run ./scripts/install-native.sh again. The binary being replaced is kept as ~/.local/bin/xcb.previous.<sha256>.

Automatic checks

On macOS, xcb can check once a day with a login item:

xcb update enable --policy notify   # record a newer release (the default policy)
xcb update enable --policy auto     # also install it
xcb update status                   # the policy, the last check, and any newer release
xcb update disable

Scheduled checks are macOS-only. On Linux, run xcb update check yourself or from your own user timer.

After an upgrade

Restart open xcb terminals. A terminal started from the old binary keeps using it.
Run xcb doctor. Provider checks carry over while the provider executables are unchanged.
Let the background supervisor finish. The old supervisor starts no new turns, lets running tasks finish, and exits; queued tasks and tasks waiting for you stay saved. Until it exits, xcb says another xcb build owns the supervisor. On macOS, xcb service status shows “supervisor idle” once it has exited.
If you use the command runner, refresh it from the matching source version.

If you’re upgrading from an 0.8 release, the first newer build to open your state moves project grants and Wordcell bindings from conversations to folders. Follow the upgrade steps first.

To go back to an earlier release, run xcb upgrade <version> --allow-downgrade. An older build may refuse state written by a newer one, so keep your state folder and read the changelog first.

Uninstall

Let running tasks finish or cancel them, then remove the login items and the binary:

xcb service uninstall   # macOS: stop starting the supervisor at login
xcb update disable      # stop the daily update check
rm ~/.local/bin/xcb

Your accounts, credentials, and history stay in ~/.local/share/xcb until you delete that folder. The table lists everything xcb creates.

What xcb creates

Paths assume the default ~/.local prefix.

What	Where	Notes
Binary	`~/.local/bin/xcb`	Also `~/.local/bin/xcb.previous.*` backups.
Installer record	`~/.local/share/xcb/install.json`	With `install-native.sh` beside it, inside the state folder.
State folder	`~/.local/share/xcb`	Accounts, credentials, conversations, tasks, settings. Or the folder in `XCB_STATE`.
Update check (macOS)	`~/Library/LaunchAgents/dev.hraness.xcb.update.plist`	Run `xcb update disable` first, or unload it with `launchctl bootout`.
Login service (macOS)	`~/Library/LaunchAgents/dev.hraness.xcb.habitat.*.plist`	Run `xcb service uninstall` while idle. Its log is in `~/Library/Logs/xcb`.
Command runner	`~/.local/share/xcb-command`	Stop the VM first: `LIMA_HOME=~/.local/share/xcb-command/lima limactl stop worker`.
Write locks	`~/.local/share/xcb-coordination`	Or the folder in `XCB_COORDINATION_ROOT`. Remove it only when no xcb process is running.
PATH line	`~/.zprofile`, `~/.bash_profile`, or `~/.profile`	Only if you installed with `XCB_ADD_PATH=yes`.

The TypeScript compatibility CLI, xcb-compat, keeps its own state in ~/.xcb. Removing xcb doesn’t sign you out of Claude Code, Codex, or Devin themselves.