BytesBrains Cruise is one endpoint in front of every model provider, with per-project keys, budgets that stop a runaway loop, and a ledger of every request. This plugin brings it into Claude Code.
/plugin marketplace add bytesbrains/cruise-claude-plugin
/plugin install cruise@bytesbrains
Put a Cruise key in your environment — a shell profile or a secret manager, not a settings file — and restart Claude Code:
export CRUISE_API_KEY=cru_live_…Then run /cruise:setup. It checks the key, confirms the MCP server answers, and — only if
you agree — routes Claude Code's own model requests through Cruise and adds the spend status line.
To try it without spending anything, use the demo: export CRUISE_BASE_URL=https://cruise-demo.bytesbrains.net
with a cru_demo_ key.
Every release is also published to npm as
@bytesbrains/claude-code-cruise,
at the same version as the marketplace. Releases from v0.1.4 on are published by this repo's
release workflow, with provenance
linking the package to the commit it was built from. The package is for your own marketplace,
for example an internal one that pins versions or mirrors a registry. Point an entry at it:
{ "name": "cruise", "source": { "source": "npm", "package": "@bytesbrains/claude-code-cruise" } }When a Claude subscription is expired or quota is exhausted, or when Claude Code is locked out by an authentication helper failure because CRUISE_API_KEY was not exported in a new terminal, Claude Code fails before it can execute any prompt or slash command. To resolve this offline:
# Run Claude on-demand through Cruise without touching global settings
npx @bytesbrains/claude-code-cruise@latest run [args...]
# or binary alias:
claude-cruise [args...]
# Enable Cruise gateway routing & status line globally
npx @bytesbrains/claude-code-cruise@latest enable
# Or configure Cruise for the current repository only (./.claude/settings.json)
npx @bytesbrains/claude-code-cruise@latest enable --local
# Switch active model or lane (globally or locally with --local)
npx @bytesbrains/claude-code-cruise@latest switch bb/agentic-coding
# Check current gateway status and auto-upgrade legacy settings
npx @bytesbrains/claude-code-cruise@latest status
# Safely revert to standard Anthropic routing offline
npx @bytesbrains/claude-code-cruise@latest disable| Mode | How | When |
|---|---|---|
| Dual-command (recommended) | Keep ~/.claude/settings.json on your subscription. Run claude for the subscription and claude-cruise (or npx @bytesbrains/claude-code-cruise@latest run) for a Cruise session. Nothing is written to disk |
You switch often, or want no chance of lockout |
| Per project | npx @bytesbrains/claude-code-cruise@latest enable --local (or /cruise:connect --local) writes ./.claude/settings.json |
A repository that should always use Cruise |
| Global | /cruise:connect or npx @bytesbrains/claude-code-cruise@latest enable |
Cruise for every session |
Slash commands run through the active model, but /cruise:disconnect does not: a plugin hook
runs it on your machine before the prompt is sent (and only for that command), so a missing, expired or refused
CRUISE_API_KEY, an exhausted budget or an unreachable gateway cannot block it
(#45). If hooks are turned off
(disableAllHooks), quit Claude Code and run npx @bytesbrains/claude-code-cruise@latest disable
instead. Both remove Cruise lanes and pinned provider models (provider/model) from every model
setting, so native routing starts clean.
Keep the @latest: without it, npx reuses whatever older copy it has cached, and one from
before v0.1.15 reports "Cruise routing is not active" and leaves a stale provider/model in
place (#40).
CLI claude-code-cruise / claude-cruise |
Standalone bootstrapper and on-demand launcher (claude-cruise, run, enable, disable, switch) with global and project-level (--local) scope |
MCP server cruise |
Three read-only tools about your key's own project: list_models (models and lanes you can reach, with prices), get_budget (what is left, and whether the next request is served), get_spend (a month's charges by model or lane). Reads CRUISE_API_KEY and CRUISE_BASE_URL from the environment |
Command /cruise:connect |
Route Claude Code through Cruise and install the spend status line in one step |
Command /cruise:disconnect |
Disconnect from Cruise gateway and restore standard Anthropic routing. Runs locally through a hook, with no model, network or key |
Command /cruise:models |
List available Cruise models and lanes with pricing, capabilities, and active selection |
Command /cruise:status |
Inspect real-time project budget limits, wallet balance, and serve/refuse status (/cruise:budget) |
Command /cruise:spend |
View monthly ledger spend breakdown by lane and by concrete model (/cruise:spend [month]) |
Command /cruise:switch |
Switch Claude Code's active model or lane in ~/.claude/settings.json. Refuses a lane or provider model while Cruise routing is off |
| Session start check | A hook that warns, without calling a model, when a model setting names a lane or provider model but no gateway is configured, and says where it is set |
Command /cruise:update |
Update Cruise plugin to latest release, refresh status line script and check settings |
Skill cruise |
When Claude works through Cruise: choosing a lane or a pinned model, and what each Cruise refusal means — budget_exhausted waits for the period, wallet_exhausted needs credit |
Skill /cruise:setup |
The guided setup above. Runs only when you invoke it, and asks before changing any file |
| Status line | Your project's spend this budget period and its state, cached for a minute. Installed by /cruise:setup |
Once /cruise:setup (or /cruise:connect) reports the MCP server answering:
/cruise:connect→ Enable Cruise gateway routing and status line in 1 step/cruise:disconnect→ Revert to native Anthropic subscription routing/cruise:models→ View reachable models, lanes, and pricing/cruise:status(or/cruise:budget) → Inspect current budget, wallet balance, and serve/refuse status/cruise:spend [month]→ Breakdown monthly spend by lane and model (e.g./cruise:spend 2026-09)/cruise:switch <model-or-lane>→ Switch active model (e.g./cruise:switch bb/agentic-coding)/cruise:update→ Update Cruise plugin to latest release and refresh status line- "Which Cruise models and lanes can this key reach, and what do they cost?" →
list_models - "How much of this project's Cruise budget is left, and will my next request be served?" →
get_budget - "What did this project spend on Cruise last month, broken down by lane?" →
get_spend - "Cruise refused with
budget_exhausted. What does that mean and what should I do?" → thecruiseskill, which explains every refusal code
The tools read only your key's own project and never change anything.
| You see | Means | Do |
|---|---|---|
/cruise:setup or the MCP server: 401 "Incorrect API key provided", with CRUISE_API_KEY unset when Claude Code started |
Claude Code sent an empty key. It reads its environment once, at start | Export the key in your shell, quit Claude Code, reopen it from that shell |
Your apiKeyHelper script is failing |
CRUISE_API_KEY is not exported in this terminal (or legacy helper configured) |
Export CRUISE_API_KEY and restart, run npx @bytesbrains/claude-code-cruise@latest status to auto-upgrade, or disable to revert offline |
| The same 401 with the key set | The key is wrong for this Cruise host, or revoked | Check CRUISE_BASE_URL against the key's prefix: a cru_demo_ key only works with the demo host. Then ask for a new key |
No cruise server in /mcp |
The plugin is not installed or not enabled | Run /plugin |
Status line: Cruise: set CRUISE_API_KEY, or /cruise:disconnect |
The key is not in the status line's environment | Export it where Claude Code starts, or run /cruise:disconnect to go back to your subscription |
Status line: Cruise: CRUISE_API_KEY is not a Cruise key |
The value has characters a Cruise key cannot have, so it was never sent | Check for quotes or a trailing newline in the value |
Status line: Cruise: no answer from <url> |
Cruise did not answer within three seconds, or answered with something else | Check the URL. The line retries after its one-minute cache |
A request refused with budget_exhausted |
The project's cap for this period is spent | Wait for the period to reset, or raise the cap |
A request refused with wallet_exhausted |
The account is out of credit. Waiting does not help | Top up the wallet |
There's an issue with the selected model (claude-opus-5-5[1m]) |
/model's 1M context option appends [1m], which Cruise answers with model_not_found. Slash commands use the same model, so they fail too |
Run /cruise:disconnect (it needs no model), or quit Claude Code and run npx @bytesbrains/claude-code-cruise@latest disable (or switch bb/agentic-coding) in a terminal. Pick a Cruise lane in /model, not a 1M option |
There's an issue with the selected model (google-ai-studio/gemini-3.8-flash) on your subscription, and /model keeps it |
env.ANTHROPIC_MODEL still names a provider/model but Cruise routing is off, so Anthropic rejects it. The env var overrides /model. The plugin warns about this when a session starts, naming where the value is set |
Run /cruise:disconnect (it needs no model), or quit Claude Code and run npx @bytesbrains/claude-code-cruise@latest disable (--local if the model is in ./.claude/settings.json). If the model is set somewhere disable does not edit (.claude/settings.local.json or a shell export), disable and status name the file or say "shell environment", with the fix (#42). Confirm with /status after restarting |
switch refuses: only resolves through a gateway, and Cruise routing is not enabled |
A lane or provider/model written with no gateway configured would make Anthropic reject every request |
Run enable first, use npx @bytesbrains/claude-code-cruise@latest run --model <id> for one session, or pass --force |
HTTP 400: Function call is missing a thought_signature in functionCall parts |
Google Gemini models with thinking enabled fail multi-turn tool calling in Claude Code (bytesbrains-cruise#543) | Switch to bb/agentic-coding or anthropic/claude-sonnet-5 (via /cruise:switch bb/agentic-coding or npx @bytesbrains/claude-code-cruise@latest switch bb/agentic-coding), or run /clear to reset conversation context |
Claude Code warning: "<model>" isn't described by this version's model catalog |
Claude Code restricts uncataloged models to 200k tokens by default | Cruise automatically sets CLAUDE_CODE_MAX_CONTEXT_TOKENS=1000000 and CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 to guarantee a 1M token context window for agentic coding and silence the warning |
To stop routing Claude Code through Cruise, remove the keys /cruise:setup added to
~/.claude/settings.json: the ANTHROPIC_* and CLAUDE_CODE_* entries under
env, plus apiKeyHelper and statusLine.
- Routing Claude Code through Cruise replaces your claude.ai subscription for as long as it is configured, and bills the Cruise key instead.
- Lanes may be served by non-Claude models, which Anthropic does not support behind a gateway. Pin a Claude model if you want Claude.
- Cruise translates Anthropic's format rather than passing it through, so Claude's extended-thinking blocks do not pass through, and Claude Code turns off on-demand tool search behind any gateway.
- Session affinity & prompt caching: When routing through Cruise lanes (like
bb/agentic-coding),x-cruise-sessionpins member model selection across multi-turn agent sessions (1-hour sliding inactivity TTL), preserving upstream prompt caching instead of redrawing a member model each turn. - Traffic class attribution:
x-cruise-class: agentictags Claude Code requests in the Cruise cost ledger, keeping agentic coding spend distinct from interactive chat or batch pipelines. - The plugin never writes your key anywhere. It reaches only the Cruise base URL you configure.
| Product | bytesbrains.com/cruise |
| Cruise docs | cruise.bytesbrains.net/docs |
| Marketplace | /plugin marketplace add bytesbrains/cruise-claude-plugin |
| npm | @bytesbrains/claude-code-cruise |
| Releases | tags. The plugin's version is in plugin.json |
| Privacy and terms | bytesbrains.com/privacy (with Cruise's own sections) · bytesbrains.com/terms |
| Issues and security | issues. Report vulnerabilities as SECURITY.md describes, not in an issue |
This repository is the source of the plugin. Develop, test and release it here. A change is a
pull request here, and a bug or request is an issue here. npm ci && npm test runs the plugin's
contract tests. CONTRIBUTING.md covers the checks and how a release is cut.
To report a vulnerability, see SECURITY.md.
Apache-2.0; see NOTICE. The plugin carries the same text in
plugins/cruise/, because that directory is all an install copies.
The license covers this plugin's code only. The Cruise service is governed by the terms of service
of BytesBrains Pte. Ltd., and the BytesBrains and Cruise names are not licensed. Releases up to
v0.1.1 keep the licence they shipped with.