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.

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.