Getting started · XCB docs

Start with the native Rust CLI. No native XCB release or @hraness/xcb npm package is published yet; the source version is not a downloadable release. Check release assets before installing.

Before you start

You need Git, Rust 1.97.1, platform build tools, and a supported provider CLI. Claude requires macOS Seatbelt or an admitted Linux bwrap configuration. The Codex and Devin candidates currently require macOS. The isolated command runner is available on macOS ARM64.

1. Build and install

git clone https://github.com/hraness/xcb.git
cd xcb
rustup toolchain install 1.97.1 --profile minimal
./scripts/install-native.sh
export PATH="$HOME/.local/bin:$PATH"
xcb --version
xcb --help

The installer builds with the lockfile and installs ~/.local/bin/xcb. Use XCB_INSTALL_PREFIX to choose another prefix. Run command -v xcb if you also have the older TypeScript CLI installed; both use the same command name. The installer records its method and keeps a verified helper beside the binary for future upgrades.

4. Keep the global install current

Updates are user-level and release-based. XCB defaults to notify; choose auto to let the macOS user scheduler install only an exact stable archive with its adjacent SHA-256 checksum. Project settings cannot change this policy.

xcb update check
xcb update enable --policy notify   # daily check, no replacement
xcb update enable --policy auto     # daily check and verified install
xcb update status
xcb upgrade
xcb update disable

No native xcb release is published yet, so checks fail closed and leave a source install untouched. After an upgrade, restart open terminals and rerun xcb doctor; provider and application qualification is tied to the exact version and digest of the installed executable.

2. Connect Claude

Install an admitted Claude Code binary: major version 2, version 2.1.268 or newer. Then create an account and complete the browser sign-in. XCB does not silently import an existing provider login.

xcb accounts add claude personal --plan Max
xcb doctor --provider claude
xcb accounts login personal
xcb accounts refresh personal
xcb models

--plan Max is a display label, not subscription verification. If XCB discovers the wrong executable, select it explicitly with xcb doctor --provider claude --executable /absolute/path/to/claude.

Using Codex or Devin? Follow the provider-specific setup and its exact runtime requirements.

3. Choose a model and open your project

Copy a full model key from xcb models; use an observed key rather than guessing a model name. Replace the placeholder below before running it.

xcb accounts default personal
xcb models default <full-model-key>
xcb --cwd /absolute/path/to/your/project

Ask XCB to explain a file or make a small change. Use /help inside the terminal for interactive commands. To run tests or builds, first set up the isolated command runner.

Come back to your work

xcb sessions
xcb resume                 # latest native session
xcb resume <session-id>
xcb --cwd /absolute/path/to/your/project run --account personal -p "Explain this repository"
xcb accounts
xcb config

resume reopens the saved session and its workspace in the interactive terminal. It is not a headless continuation command. A JSON run includes the session ID for later use with xcb resume.

State and updates

Native sessions and credentials live in ~/.local/share/xcb. Override the root with --state /absolute/path or XCB_STATE. The TypeScript compatibility CLI uses ~/.xcb; keep their state directories separate.

After an XCB or provider upgrade, restart open XCB terminals and rerun doctor. A new provider version is not automatically admitted. Keep the source checkout matching your installed CLI for command-runner setup and updates.