Excalibur (xcb) routes coding tasks across the Claude and Codex subscriptions you already pay for. Each task runs on an account that is signed in, idle, and not at a known usage limit, on a model that fits the work. Send work through the headless CLI, JSON contract, or SDK. The former interactive terminal and hosted remote commands are removed from the current source build.
Status: Latest release for macOS ARM64, Linux x86_64 and ARM64, and Windows x86_64; other hosts build from source. MIT licensed.
This guide follows the current source build. Unreleased commands require a source build until they appear in the release notes.
Site · Docs · Getting started · Route contract · TypeScript SDK · Compare · Changelog
With fresh Claude and Codex usage reports, xcb favors unused quota approaching a reset while preserving the task's quality requirements and your chosen provider, account, or model. You can also continue a Claude or Codex conversation by importing work active in the last 24 hours.
On macOS with Apple silicon or Linux x86_64 or ARM64 (glibc 2.34 or newer), one command
downloads the latest release for your platform, checks its SHA-256 checksum,
and installs ~/.local/bin/xcb:
curl -fsSL https://xcb.sh/install.sh | shNew release installs update automatically before an interactive run or
doctor command, at most once a day and only when no other
xcb command or service is using the installation. Run xcb update disable to
turn this off, or xcb update enable --policy notify for notices only. Existing
saved preferences stay in force. HRANESS_NO_UPDATE=1, CI, JSON output, and
noninteractive commands skip automatic updates.
xcb upgrade installs the latest release manually. XCB_VERSION installs and
pins one exact version, XCB_INSTALL_PREFIX replaces ~/.local, and
XCB_ADD_PATH=yes adds the bin folder to your shell profile. Source,
package-manager, and older installs without a checksum-bound install record do
not self-update; rerun the release installer to create a supported install.
To run Claude Code on Windows, install the Linux build of xcb inside WSL2 with
the command above. Claude is the supported provider on Linux; Codex
requires macOS. Releases also carry a native
Windows x86_64 build for local task inspection, xcb doctor, accounts, and
xcb route, which refuses provider work with those WSL2 steps. Install it from PowerShell:
irm https://xcb.sh/install.ps1 | iexIt checks the zip's SHA-256 checksum and installs
%LOCALAPPDATA%\Programs\xcb\bin\xcb.exe; state lives in
%LOCALAPPDATA%\xcb. The binary is not code-signed yet, so SmartScreen may
ask before its first run.
On other hosts, build with Git, Rust 1.97.1, and the platform's build tools:
git clone https://github.com/hraness/xcb.git && cd xcb
rustup toolchain install 1.97.1 --profile minimal
./scripts/install-native.shUpgrade and uninstall covers updates and removal.
Install Claude Code 2.1.268 or later, then connect an account and run a task:
xcb setup claude
xcb run -p "Explain this repository"xcb setup lets you choose an existing account or add another, checks the
Claude Code build, opens browser sign-in, and loads the account's models. New
Claude accounts keep a model-only token in xcb's state folder. Accounts connected
for shared browser access use a dedicated xcb Keychain entry on macOS. Both are
separate from your usual Claude Code login. xcb setup codex
works the same way; see accounts and models
for sign-in and import options.
xcb run picks an account and model and prints the result. xcb --json route
runs exactly one turn and returns a JSON result; its caller owns any retry.
For durable managed work, submit an explicitly scoped backlog item with
xcb backlog add /absolute/path/to/project "Fix the failing test" --ready.
Inspect it with xcb tasks and xcb tasks show <task-id> --json.
xcb tasks cancel <task-id> --revision <revision>requests cancellation.xcb steer <task-id> <guidance>adds guidance for the task's next turn.xcb attentionshows questions;xcb backlog replyanswers one.xcb conversations --new --jsoncreates a project view without opening a UI.
The headless command guide covers retained local operations.
Bring conversation context into xcb so your next task can use its account and model selection. Discovery and import use a 24-hour activity window by default:
xcb sessions discover
xcb sessions import --recent
xcb conversations # saved conversations, including imports
xcb history <conversation-id>
xcb backlog add <conversation-id> "Continue the work" --readySubmit a backlog task in the imported conversation to start work. Import copies user and
assistant text, preserves the original files, and does not take over the
provider process. For a conversation started in your home folder, select one
result with xcb sessions import <candidate-id> --workspace /path/to/project.
Session import covers provider filters and limits.
From an agent or script, xcb --json route reads one JSON task on stdin,
picks an account and model that can take it, runs one turn, and prints one
JSON result:
echo '{"version":1,"workspace":"/absolute/path/to/project","task":"Fix the failing parser test"}' \
| xcb --json route{"version":1,"status":"completed","requestId":"route_…","session":"s_…",
"route":{"provider":"claude","account":"a_…","model":"claude/sonnet/low","label":"Sonnet · low","reason":"…"},
"state":"idle","outcome":{"terminal":"completed","joined":true,"effects":"settled","pending_attention":false,"failure":null},
"text":"…"}Add "dryRun": true to see the chosen route without running anything, or pin
provider, account, or model. A failure exits 1 with a code such as
unavailable, busy, or needs_input. The route contract
lists every field.
From your own app, the TypeScript SDK's createSubscriptionRouter runs a
task on the account and model your app names, and holds that account until
the provider process exits; it does not choose them for you. Install it with
npm install @hraness/xcb; the SDK quickstart has a complete
example.
| Provider | Supported builds | Status |
|---|---|---|
| Claude | Claude Code 2.1.268 or later within version 2 | Coding workflow passed on macOS ARM64 with the tested account. On Linux, Claude runs after you run xcb's sandbox checks on that machine. |
| Codex | Codex CLI 0.159.0, 0.158.0, 0.157.1, or 0.156.1 on macOS ARM64 | Coding workflow passed on macOS ARM64 with the tested account and Codex CLI 0.158.0. |
xcb checks each provider executable's version, and for Codex its
exact SHA-256, before it runs anything. xcb doctor shows what it found.
- Filter: keep the accounts that can take the task now: supported provider build, signed in, enabled, idle, not at a known usage limit, with a recently seen model.
- Rank: order those models by relative quality, cost, and speed for the kind of task. Fresh Claude and Codex usage reports favor unused quota approaching a reset within the task's quality requirements. Long prompts get the highest-quality model available.
- Hold: lock the chosen account so no other task can use it, and run the provider in an OS sandbox with xcb's file tools for one project folder.
- Record: when the provider process exits, record how the run ended. If xcb can't confirm that, it keeps the account held and doesn't retry.
How routing works covers each step.
Tasks that require an existing signed-in browser or native desktop control
stay with Codex and prefer Astra, including after a retry or handoff. Use
xcb run --signed-in-browser or xcb run --desktop to state that requirement.
Claude can hand these tasks to Codex after their current run ends
safely. xcb tools setup-computer connects the installed desktop computer-use
plugin on macOS. xcb tools setup-browser shares Claude's Chrome extension
across providers and opens full Claude sign-in when needed. This sign-in uses
a dedicated xcb Keychain entry on macOS. See
browser and shared tools.
xcb --help # discover local commands
xcb conversations --new --json # a project view for this directory
xcb run -p "Explain this repository" # one task here; prints the answer
xcb tasks # managed tasks across projects
xcb attention # questions and approvals waiting on you
xcb accounts # accounts, usage, and which need you
xcb usage # your token use by day, agent and model
xcb doctor # provider builds and unfinished runs
xcb upgrade # install the latest verified release
xcb help advanced # project agents and extensionsAccounts, credentials, and task history live in ~/.local/share/xcb, outside
your projects (--state or XCB_STATE moves it). The
CLI and configuration reference lists every
command, setting, and exit code.
xcb usage shows your token use across coding agents by day, agent, provider,
and model. The numbers come from aicharts, which keeps a
daily record on your computer and uploads nothing, so it needs the aicharts
command installed (get it). xcb usage enable
has aicharts collect four times a day, xcb usage report --csv exports the
rows, and agents can read the same record through aicharts mcp. Quota left
on each subscription stays in xcb accounts.
- Tools: providers use xcb's workspace tools and registered host MCP servers. Native shells and unrelated provider plugins remain unavailable; see browser and shared tools.
- Tests and builds: the command runner is an offline Linux VM on macOS ARM64; Git is read-only there, and native macOS builds can't run.
- Concurrency: each account runs one provider turn at a time by default;
max_runs_per_accountinconfig.json(1–32) raises how many tasks may share an account, while sign-in and account checks still take the account alone. Tasks in the same project folder take turns. - Remote devices: the hosted remote commands are removed. Valhalla integration is planned, not shipped (north star).
- Managed harness: the self-tuning harness is in development; the current build does not run self-modifying routing policies (design).
- Claude Code or Codex alone: enough when one subscription covers your work, and you keep all of the tool's built-in tools, MCP servers, and plugins. xcb supplies workspace tools, its offline command runner on macOS, and registered host tool servers across providers.
- Account switchers such as claude-swap: change which login Claude Code uses. xcb picks an account for each task across Claude and Codex, and sandboxes each run.
- Claude Code Router and OpenRouter: send each API request to a provider or model you choose, usually paid per token. xcb never touches API traffic; it routes whole tasks to subscriptions you already pay for.
- Conductor and Claude Squad: give each agent a Git worktree and a merge flow. xcb has no worktree or pull request flow.
The name xcb is short for Excalibur. xcb was formerly AgentMixer.
The compatibility reference covers the TypeScript
package and its xcb-compat CLI. Supported Unix Bun/npm global copies update
before interactive work; xcb-compat update disable turns that off. SDK imports
never update. Contributing ·
Security · MIT license