@bytesbrains/claude Code Cruise

GitHub ActionsClaim this server

BytesBrains Cruise for Claude Code: your key's models, budget and spend over MCP, a skill for lanes and refusals, a spend status line, and guided setup. The package root is the plugin root, for a mark

Devops Developer Tools

Add to Cursor Add to VS Code Run on PlugMCPClaim this server

GitHub npm Website

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "bytesbrains-claude-code-cruise": {4      "command": "npx",5      "args": [6        "-y",7        "@bytesbrains/[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @bytesbrains/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add bytesbrains-claude-code-cruise -- npx -y @bytesbrains/claude-code-cruise@0.1.17

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "bytesbrains-claude-code-cruise": {4      "command": "npx",5      "args": [6        "-y",7        "@bytesbrains/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.1.17
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Overview

About @bytesbrains/claude Code Cruise

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install @bytesbrains/claude Code Cruise?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does @bytesbrains/claude Code Cruise need an API key?

No required environment variable is listed on this record.

What transport does @bytesbrains/claude Code Cruise use?

@bytesbrains/claude Code Cruise runs locally over stdio.

When was @bytesbrains/claude Code Cruise last checked?

Last checked 2026-10-28. BytesBrains Cruise for Claude Code: your key's models, budget and spend over MCP, a skill for lanes and refusals, a spend status line, and guided setup. The package root is the plugin root, for a marketplace's npm source.

From the publisher

Documentation

Install

/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.

From npm

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" } }

Standalone CLI Bootstrapper

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

Switching between Cruise and your Claude subscription

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).

What is inside


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`

Try it

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?" → the cruise skill, which explains every refusal code

The tools read only your key's own project and never change anything.

Troubleshooting

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.

Worth knowing

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-session pins 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: agentic tags 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.

Links


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

Development

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.

Licence

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.

# 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

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

You see

Means

/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

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