shunt
Shunt Claude Code agents to any model — selective, per-agent inference-layer routing proxy
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pleaseai/shunt with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pleaseai/shunt'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/pleaseai--shunt)HTML
<a href="/listings/pleaseai--shunt"><img src="/api/listings/pleaseai--shunt/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# Homebrew (macOS / Linux) brew install pleaseai/tap/shunt # Cargo, directly from the source repository cargo install --git https://github.com/pleaseai/shunt
New versions are distributed through Homebrew and prebuilt binaries (macOS/Linux, arm64/x64) attached to each [GitHub release](https://github.com/pleaseai/shunt/releases); the crates.io package stops at the last version published there. See [Installation](https://shunt.sh/getting-started/installation/) for prebuilt-binary and from-source instructions.
The `cargo install` line above builds without the admin dashboard: its bundle needs Node.js 22.12+ and is embedded only by `--features ui`, which Homebrew and the release binaries already enable. Everything else — including the admin JSON API — is identical either way. [Installation](https://shunt.sh/getting-started/installation/) has the from-source steps.
Run as a service (macOS/Homebrew)
brew services start shunt
Logs go to `$(brew --prefix)/var/log/shunt.log`. `brew services stop` sends `SIGTERM`, and shunt drains in-flight requests before exiting — for up to `[server] shutdown_timeout_seconds` (default 30; changing this one does need a restart), after which shunt stops waiting and exits, so a quiet SSE stream cannot hold the process open forever. On Unix, Antigravity agent turns are terminated when shutdown starts so their isolated process groups cannot hold the drain open. Editing the config file afterwards doesn't need a restart — it [hot-reloads](docs/config-reload.md) automatically. Details: [Running as a service](docs/running.md#run-as-a-background-service-homebrew).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 61 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
- "name": "shunt",
- "owner": {
- "name": "pleaseai",
- "url": "https://github.com/pleaseai/shunt"
- },
- "metadata": {
- "description": "Claude Code plugins for the shunt gateway: subagents for the models it diverts to other providers, and a mod for the gateway's own pool usage."
- },
- "plugins": [
- {
- "name": "shunt",
- "source": "./plugins/shunt",
- "description": "A Claude Mod for the gateway itself: a band above the prompt shows the shared account pool's usage and reset times (the session's own rate limits off shunt), and /shunt:usage shows the pool's full breakdown, read from GET /usage. Requires function hooks (early access).",
- "keywords": ["usage", "quota", "pool", "usage-band", "mod", "function-hooks"]
- },
- {
- "name": "shunt-codex",
- "source": "./plugins/shunt-codex",
- "description": "Subagents on ChatGPT/Codex GPT-6 models (Sol, Luna) and GPT-5.6 models (Luna, Sol, Terra), routed through shunt at the inference layer.",
- "keywords": ["codex", "chatgpt", "gpt-6", "gpt-5.6"]
- },
- {
- "name": "shunt-xai",
- "source": "./plugins/shunt-xai",
- "description": "Subagents on xAI Grok models (grok-4.6, grok-4.5, grok-build-0.1), routed through shunt at the inference layer. EXPERIMENTAL — the xAI provider is not yet verified against the live API.",
- "keywords": ["xai", "grok"]
- },
- {
- "name": "shunt-kimi",
- "source": "./plugins/shunt-kimi",
- "description": "Subagent on Moonshot AI's kimi-k2.7-code, routed through shunt at the inference layer via Moonshot's Anthropic-compatible endpoint.",
- "keywords": ["kimi", "moonshot"]
- },
- {
- "name": "shunt-deepseek",
- "source": "./plugins/shunt-deepseek",
- "description": "Subagents on DeepSeek models (deepseek-v4-pro, deepseek-v4-flash), routed through shunt at the inference layer via DeepSeek's Anthropic-compatible endpoint.",
- "keywords": ["deepseek"]
- },
- {
- "name": "shunt-zai",
- "source": "./plugins/shunt-zai",
- "description": "Subagents on Z.ai GLM models (glm-5.2, glm-4.7), routed through shunt at the inference layer via Z.ai's Anthropic-compatible endpoint.",
- "keywords": ["zai", "glm"]
- },
- {
- "name": "shunt-minimax",
- "source": "./plugins/shunt-minimax",
- "description": "Subagent on MiniMax-M3 (1M context), routed through shunt at the inference layer via MiniMax's Anthropic-compatible endpoint.",
- "keywords": ["minimax"]
- },
- {
- "name": "shunt-mimo",
- "source": "./plugins/shunt-mimo",
- "description": "Subagent on Xiaomi's mimo-v2.5-pro, routed through shunt at the inference layer via Mimo's Anthropic-compatible endpoint.",
- "keywords": ["mimo", "xiaomi"]
- }
- ]
- }
README.md · README · 316 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # shunt
- Offline credential import: `shunt import opencodex --dry-run` previews compatible API keys and Cursor/Command Code access tokens. Exports create new private snapshots without changing existing settings or copying refresh tokens. See [credential import](docs/credential-import.md).
- [](https://github.com/pleaseai/shunt/actions/workflows/ci.yml)
- [](https://app.codspeed.io/pleaseai/shunt?utm_source=badge)
- [](https://sonarcloud.io/summary/new_code?id=pleaseai_shunt)
- [](https://codecov.io/gh/pleaseai/shunt)
- [](#license)
- [](https://www.greptile.com/?utm_source=oss_badge&utm_medium=readme&utm_campaign=greptile_for_open_source)
- **English** · [한국어](README.ko.md) · [日本語](README.ja.md) · [简体中文](README.zh-CN.md)
- > Shunt Claude Code to any model.
- `shunt` is a spec-compliant [Claude Code LLM gateway](https://code.claude.com/docs/en/llm-gateway-protocol): a transparent proxy that, for the **models you map**, diverts inference to another LLM provider at the **inference layer**. It routes by the request's `model` id — everything else passes through to Anthropic unchanged (the "shunt"; the fallback is configurable via `server.default_provider`).
- The name is the mechanism: an electrical/railway *shunt* diverts a selected part of the flow onto a parallel path. Here, a mapped model's inference is diverted to another provider while Claude Code's tools and skills stay intact.
- Providers for OpenAI, ChatGPT/Codex, xAI, Grok, Cursor, Kimi Code, Zhipu, MiniMax China, OpenCode Zen, Cheaper Inference, Gemini, Antigravity, and Anthropic passthrough ship built in — several of them reusing a subscription you already pay for. Any Anthropic-Messages-compatible backend is one config table away, with no code changes. See [Providers](#providers).
- > [!NOTE]
- > `shunt` is pre-1.0 software under active development. Per [SemVer](https://semver.org/#spec), `0.x` releases may include breaking changes to configuration keys, the CLI, and behavior — check the [release notes](https://github.com/pleaseai/shunt/releases) before upgrading.
- ## Install
- ```bash
- # Homebrew (macOS / Linux)
- brew install pleaseai/tap/shunt
- # Install script (macOS / Linux) — prebuilt binary from the GitHub release
- curl -fsSL https://shunt.sh/install.sh | sh
- # Cargo, directly from the source repository
- cargo install --git https://github.com/pleaseai/shunt
- ```
- New versions are distributed through Homebrew and prebuilt binaries (macOS/Linux, arm64/x64) attached to each [GitHub release](https://github.com/pleaseai/shunt/releases); the crates.io package stops at the last version published there. See [Installation](https://shunt.sh/getting-started/installation/) for prebuilt-binary and from-source instructions.
- The `cargo install` line above builds without the admin dashboard: its bundle needs Node.js 22.12+ and is embedded only by `--features ui`, which Homebrew and the release binaries already enable. Everything else — including the admin JSON API — is identical either way. [Installation](https://shunt.sh/getting-started/installation/) has the from-source steps.
- ### Run as a service (macOS/Homebrew)
- ```bash
- brew services start shunt
- ```
- Logs go to `$(brew --prefix)/var/log/shunt.log`. `brew services stop` sends `SIGTERM`, and shunt
- drains in-flight requests before exiting — for up to `[server] shutdown_timeout_seconds`
- (default 30; changing this one does need a restart), after which shunt stops waiting and exits, so
- a quiet SSE stream cannot hold the process open forever. On Unix, Antigravity agent turns are terminated when shutdown starts so
- their isolated process groups cannot hold the drain open. Editing the config file
- afterwards doesn't need a restart — it [hot-reloads](docs/config-reload.md) automatically. Details:
- [Running as a service](docs/running.md#run-as-a-background-service-homebrew).
- ## Quickstart
- ```toml
- # shunt.toml — route a gpt-* id to your ChatGPT subscription
- # [[routes]] is legacy for exact ids; prefer [models.upstream_model].
- [[routes]]
- model = "gpt-5.6-sol"
- provider = "codex" # reuses `codex login`; use `openai` for OPENAI_API_KEY
- ```
- ```bash
- codex login # provider credential
- shunt run # -> listening on 127.0.0.1:3001
- export ANTHROPIC_BASE_URL=http://127.0.0.1:3001
- export ANTHROPIC_CUSTOM_MODEL_OPTION="gpt-5.6-sol"
- claude # /model -> pick gpt-5.6-sol
- ```
- Unmapped models (all your `claude-*` ids) keep working exactly as before — shunt forwards them to Anthropic with your own credential. Full walkthrough: [Quickstart](https://shunt.sh/getting-started/quickstart/).
- ### Starter configuration
- `shunt init` creates a commented `shunt.toml` in an existing directory. Keep the default passthrough starter, or scaffold ordered upstream presets without changing the fallback for unmapped models:
- ```bash
- shunt init
- shunt init --upstream codex --upstream kimi
- ```
- ### Agent-native setup blueprints
- `shunt add` retrieves embedded Markdown implementation guides for coding agents. List the available upstream blueprints with `shunt add upstream`, or pipe one directly into an agent:
- ```bash
- shunt add upstream kimi --print | claude
- shunt add upstream https://provider.example/docs --print | claude
- ```
- The command is offline and read-only: it prints guidance but never edits files, installs anything, or accesses the network. Use `shunt add provider <absolute-url>` when contributing support for a genuinely new provider protocol.
- ## Providers
- A provider is either an ordered `[[upstreams]]` entry or a legacy `[providers.<name>]` TOML table (under YAML, an entry in the corresponding sequence or mapping). Two adapter kinds cover most upstreams: `kind = "anthropic"` (the upstream speaks Anthropic Messages; passed through, optionally with a different key) and `kind = "responses"` (the upstream speaks the OpenAI Responses API; shunt translates Anthropic Messages ⇄ Responses, streaming included, and emulates `stop_sequences` gateway-side because the Responses API has no `stop` parameter). A third native kind, `kind = "cursor"`, bridges Cursor's ConnectRPC/protobuf AgentService so a Cursor subscription is reachable through the same Anthropic-Messages interface.
- Ordered upstreams enable cross-provider failover. Declaration order is the attempt order; a model's `upstream_model` map selects the participating entries and maps its public id to each backend's id:
- ```toml
- [server]
- default_provider = "anthropic-primary"
- [[upstreams]]
- name = "anthropic-primary"
- provider = "anthropic" # preset: kind, base_url, and default auth
- auth = { mode = "claude_oauth", account = "primary" }
- [[upstreams]]
- name = "codex-fallback"
- provider = "codex" # defaults to chatgpt_oauth
- [[models]]
- id = "claude-opus-4-8"
- [models.upstream_model]
- anthropic-primary = "claude-opus-4-8"
- codex-fallback = "gpt-5.6-sol"
- ```
- This chain tries `anthropic-primary` and then `codex-fallback`. `auth` accepts either a mode string or a map; `claude_oauth` and `chatgpt_oauth` maps can narrow credentials with `account = "name"` or `accounts = [...]`. Legacy `[providers.<name>]` remains supported and becomes implicit name-sorted upstreams. Do not declare both forms: mixing `[[upstreams]]` with `[providers.*]` is a configuration error. See the [configuration reference](https://shunt.sh/reference/configuration/) for presets, failure classes, and migration details.
- ### Built in
- These providers are seeded by default, so `provider = "<name>"` routes to them with no `[providers.*]` table of your own — **but only while you declare no `[[upstreams]]`**. An ordered `[[upstreams]]` list replaces the provider map entirely, so under that form every provider you route to must be declared there, presets included:
- | Name | Kind | Auth | Backend |
- | :-- | :-- | :-- | :-- |
- | `anthropic` | `anthropic` | passthrough or Claude OAuth account pool | `api.anthropic.com` — forwards the caller's credential by default; `auth = "claude_oauth"` enables pooled subscription credentials |
- | `openai` | `responses` | `OPENAI_API_KEY` | `api.openai.com/v1` |
- | `codex` | `responses` | ChatGPT OAuth | `chatgpt.com/backend-api` — reuses `~/.codex/auth.json` (`codex login`) |
- | `xai` | `responses` | `XAI_API_KEY` | `api.x.ai/v1` — the developer API, billed per token |
- | `grok` | `responses` | xAI OAuth | `cli-chat-proxy.grok.com/v1` — the Grok CLI proxy; reuses `~/.shunt/xai-auth.json` (`shunt login xai` with a SuperGrok / X Premium+ subscription), or named accounts under `~/.shunt/accounts/xai` (`shunt login xai --name <name>`, pooled with failover; the legacy file is used only while that pool is empty, so adding the first named account switches credentials) |
- | `cursor` | `cursor` | Cursor OAuth | `api2.cursor.sh` — reuses `~/.shunt/cursor-auth.json` (`shunt login cursor`) |
- | `gemini` | `gemini` | Google OAuth | `cloudcode-pa.googleapis.com` — Google Code Assist backend; reuses `~/.gemini/oauth_creds.json` |
- | `antigravity` | `antigravity` | Antigravity OAuth | `daily-cloudcode-pa.googleapis.com` — Google Antigravity backend over HTTP; uses `~/.shunt/antigravity-auth.json` (`shunt login antigravity`), or named accounts under `~/.shunt/accounts/antigravity` (`shunt login antigravity --name`, selected via `accounts = [...]`) |
- | `antigravity-cli` | `antigravity_cli` | None (local CLI) | **Deprecated.** Local `agy` binary — same backend via subprocess; superseded by `antigravity` above |
- Ordered `[[upstreams]]` entries additionally accept the presets `kimi`, `kimi-code`, `zhipu`, `minimax-cn`, `opencode`, `cheaperinference`, and `chatgpt-plan`, which fill in `kind`, `base_url`, and the default auth for those backends.
- **ChatGPT plan (Sign in with ChatGPT).** The `chatgpt-plan` preset spends a ChatGPT plan through OpenAI's "Sign in with ChatGPT" token-sharing preview on `api.openai.com/v1/responses`, separate from the `codex` provider above. Sign in with `shunt login chatgpt-plan --name <account>` (a browser callback on `127.0.0.1:1455`, or paste the callback URL on a remote host), add an ordered `[[upstreams]]` entry with `provider = "chatgpt-plan"` (the preset fills in `kind`, `base_url`, and `auth = "chatgpt_plan_oauth"`) and map a model to it, as below. Several named accounts form a pool that rotates when one hits its plan usage limit, and `shunt logout chatgpt-plan --name <account>` revokes and clears one. The preview rejects some request parameters and a usage limit hit after output starts ends the stream instead of rotating; see the [ChatGPT plan guide](https://shunt.sh/guides/chatgpt-plan/).
- ```toml
- [[upstreams]]
- name = "anthropic"
- provider = "anthropic" # preset: Claude models pass through to Anthropic
- [[upstreams]]
- name = "chatgpt-plan"
- provider = "chatgpt-plan" # preset: kind, base_url, and auth = "chatgpt_plan_oauth"
- [[models]]
- id = "gpt-6.1-sol"
- [models.upstream_model]
- chatgpt-plan = "gpt-6.1-sol"
- ```
- Per-provider setup, model ids, and caveats live under [Providers](https://shunt.sh/guides/providers/) — including xAI's OAuth tier gate ([xAI / Grok](https://shunt.sh/guides/xai/)), Cursor's agent-mode prefixes ([Cursor](https://shunt.sh/providers/cursor/)), and Antigravity's two transports and the `kind = "antigravity"` migration ([Antigravity](https://shunt.sh/providers/antigravity/)).
- > [!WARNING]
- > `antigravity-cli` is deprecated and is **arbitrary code execution**: it runs the local `agy` binary agentically with `--dangerously-skip-permissions`, as the user running shunt. Keep its `sandbox` setting on, keep the bind on loopback, and prefer the `antigravity` provider, which needs none of this. See [the deprecated transport](https://shunt.sh/guides/providers/#the-deprecated-antigravity-cli-transport).
- ### Any Anthropic-compatible backend
- One table, no code changes:
- | Provider | `base_url` | Example model IDs |
- | :-- | :-- | :-- |
- | Kimi (Moonshot) | `https://api.moonshot.ai/anthropic` | `kimi-k3[1m]`, `kimi-k2.7-code` |
- | Kimi Code (subscription, OAuth) | `https://api.kimi.com/coding` | use the ids your subscription exposes |
- | DeepSeek | `https://api.deepseek.com/anthropic` | `deepseek-v4-pro`, `deepseek-v4-flash` |
- | Z.ai (GLM) | `https://api.z.ai/api/anthropic` | `glm-5.2`, `glm-4.7` |
- | Zhipu (GLM China) | `https://open.bigmodel.cn/api/anthropic` | `glm-5.3`, `glm-5.3-flash` |
- | MiniMax | `https://api.minimax.io/anthropic` | see [MiniMax docs](https://platform.minimax.io/docs/token-plan/claude-code) |
- | MiniMax China | `https://api.minimax.cn/anthropic` | `MiniMax-M3` |
- | OpenCode Zen | `https://opencode.ai/zen` | `claude-fable-5-1`, `gpt-6-astra` — curated cross-vendor catalog; reads `x-api-key` |
- | Cheaper Inference | `https://api.cheaperinference.com` | `gpt-5.4`, `deepseek-v4-flash`, `glm-5.3` — OpenAI-compatible gateway with a Messages endpoint |
- | OpenRouter | `https://openrouter.ai/api` | `anthropic/claude-opus-4.8` |
- | Vercel AI Gateway | `https://ai-gateway.vercel.sh` | `anthropic/claude-opus-4.8` |
- ```toml
- [providers.kimi]
- kind = "anthropic"
- base_url = "https://api.moonshot.ai/anthropic"
- auth = "api_key"
- api_key_env = "MOONSHOT_API_KEY"
- [[routes]]
- model = "kimi-k3[1m]"
- provider = "kimi"
- ```
- Every row above but one takes `auth = "api_key"`. **Kimi Code** is the exception: a separate, subscription-billed service from the metered Moonshot API — different host, OAuth instead of an API key, and a built-in `kimi-code` preset. That preset resolves only inside an ordered `[[upstreams]]` entry, so declare it there (it is not in the seeded provider map) and log in. See [Kimi Code](https://shunt.sh/providers/kimi/#kimi-code-oauth-subscription).
- ### Reusing a subscription
- OpenAI's Thibault Sottiaux has publicly welcomed running Codex through other coding harnesses:
- > Share the recipe. People want to know how to use GPT-5.6 Sol in CC. We don't discriminate on the harness. ([Source](https://x.com/thsottiaux/status/2075830097488249060))
- He [followed up](https://x.com/thsottiaux/status/2076119366647894371) by walking through pointing Claude Code ("your orange crab") at GPT-5.6 Sol himself — exactly the inference-layer swap `shunt` performs, no separate app required.
- That said, reusing your ChatGPT/Codex or SuperGrok subscription (or Kimi, Cursor, or other backends) from an unofficial client is your own call — a public welcome doesn't guarantee future policy or account enforcement. Use at your own risk.
- **Antigravity is the exception where the terms are explicit.** Google's [Antigravity terms](https://antigravity.google/terms) state that "using third party software, tools, or services to access the Service (e.g. using OpenClaw with Antigravity OAuth) is a breach of this Agreement" and that such a breach "may be grounds for suspension or termination of your Antigravity and/or Gemini CLI accounts". shunt's `antigravity` provider is exactly that — third-party software using Antigravity OAuth — so routing through it falls squarely under that clause. Decide with that in mind before running `shunt login antigravity`.
- ## Optional server features
- Unless a row says otherwise, these are **off by default** — absent its config table, the feature registers no routes and starts no background work.
- | Feature | Enable with | Documentation |
- | :-- | :-- | :-- |
- | Anthropic multi-account pooling — session-to-account bindings that move when the bound account cannot serve or has been near quota for 60 s, placed by `[server.pool] assignment` (`spread` by default, or `soonest_weekly_reset`), quota-aware rotation, predictive avoidance, per-window hard caps (`max_utilization*`) that exclude an account and fail over to the next upstream when the pool is capped out | `auth = "claude_oauth"` with two or more accounts; `[server.pool]` is optional tuning | [How-to](https://shunt.sh/guides/anthropic-multi-account/) |
- | Codex multi-account pooling — the same session-to-account bindings, `x-codex-*` window tracking, slow-start ramp, re-probing, per-window hard caps (`max_utilization*`) that exclude an account and fail over to the next upstream when the pool is capped out | `auth = "chatgpt_oauth"` with two or more accounts; `[server.pool]` is optional tuning | [How-to](https://shunt.sh/guides/codex-multi-account/) |
- | Inbound Codex endpoint — point the **Codex CLI** at shunt over HTTP/SSE or WebSocket and pool it, with opt-in per-model routing | `[server.codex_endpoint]` | [How-to](https://shunt.sh/guides/inbound-codex-endpoint/) |
- | Learned prefill routing (`type = "prefill_router"`) | compile-time opt-in — `cargo build --release --features prefill-router` (**off by default**; not in release binaries or the Homebrew formula, which are built `--features ui`), plus a `[models.router]` table with `type = "prefill_router"`, a router checkpoint on disk, and a Python environment carrying `torch` and `transformers` | [Reference](https://shunt.sh/reference/configuration/#type--prefill_router) |
- | LLM-judge routing (`type = "llm_classifier"`, `type = "composite"`) — a judge model picks the destination per turn, per `classify_trigger`; never served to the client | a `[models.router]` table with `type = "llm_classifier"` (`mode = "capability"` or `"custom"`) or `type = "composite"`, or a classifier-form `[models.subagents]` overlay | [Reference](https://shunt.sh/reference/configuration/#type--llm_classifier) |
- | Judged-turn routing (`mode = "escalation"`, `type = "advisor"`) — the answer is made first, held back, and served only after a judge or reviewer rules on the completed turn; streaming callers get it replayed once the verdict is in | a `[models.router]` table with `type = "llm_classifier"` and `mode = "escalation"`, or with `type = "advisor"` | [Reference](https://shunt.sh/reference/configuration/#type--advisor) |
- | Verify-only inbound JWT — accept a JWT minted by your own identity provider, verified against its JWKS; shunt issues nothing, so the client stays in first-party mode | `[server.auth]` with one or more `[[server.auth.jwt]]` entries, each with `issuer`, `audience`, and `email_domains` or `allowed_emails` (or, for workload identity such as GitHub Actions, `require` / `subject_prefix` plus `identity_claim`); `jwt_header` / `jwt_cookie` carry the token for Codex CLI `gateway_oauth` on the inbound Codex endpoint (`[server.codex_endpoint]`) | [Reference](https://shunt.sh/reference/configuration/#serverauthjwt-optional) |
- | Claude apps gateway login — OAuth device flow, managed settings, per-user policy, Claude Desktop bootstrap (`GET /user/bootstrap`) | `[server.gateway]` with `public_url`, a 32-byte-or-longer JWT secret, and static users or `[server.gateway.oidc]`; Desktop bootstrap also needs `[server.gateway.desktop_bootstrap]` with a `template` path | [How-to](https://shunt.sh/guides/gateway-login/) |
- | Gateway telemetry ingest — verbatim OTLP relay for managed clients | a configured `[server.gateway]`, plus `[server.gateway.telemetry]` with a non-empty `forward_to` | [Reference](https://shunt.sh/reference/configuration/#servergatewaytelemetry-optional) |
- | Admin web surface — accounts and usage dashboard, browser provisioning | `[server.admin]` with an admin credential (`tokens_env`, `tokens_file`, or a `write_keys` entry; a `read_keys` entry alone brings the dashboard up read-only — it signs in and serves every view, but provisioning needs write) — **or** `shunt dashboard setup`, which writes the table and mints a token, but only when `[server.admin]` is absent: against an existing block it leaves your credential untouched and only adds a missing `[server.oauth_usage]`. The dashboard itself is served from a bundle only a `--features ui` build embeds — prebuilt release binaries and the Homebrew formula have it, a plain `cargo build`/`cargo install` does not | [How-to](https://shunt.sh/guides/admin-remote-provisioning/) |
- | Pool account controls — pause an account, or rank available accounts by soonest quota reset, from the dashboard or admin API, at runtime, with no `shunt.toml` edit or restart | `[server.admin]` write credential; `sort_by_reset` also has an equivalent `[server.pool]` config key | [How-to](https://shunt.sh/guides/pool-account-controls/) |
- | Spend limits — organization- and user-scoped caps stored through an Admin API and enforced on `/v1/messages` requests the gateway pays for — chains made only of passthrough or `noop` routes are neither enforced nor metered (`429 billing_error`, per-principal `anthropic-ratelimit-*` headers, `GET /v1/organizations/spend_limits/effective`) — and on the inbound Codex endpoint, HTTP and WebSocket, where an over-cap turn gets `429 usage_limit_reached` and counts toward the same caps; `[server.spend.pricing]` sets the multiplier and per-upstream/model override rates the meter prices requests with (GPT/Codex models have no built-in prices: add override rows or they bill at the unknown-model rate) | `[server.admin]` with an admin credential (`tokens_env`, `tokens_file`, or a `write_keys`/`read_keys` entry — read-tier serves the GETs) + `[server.spend]` | [Reference](https://shunt.sh/reference/configuration/#serverspend-optional) |
- | Client usage endpoint — sanitized, aggregated pool headroom at `GET /usage` | `[server.usage]`, plus `[server.auth]` (client tokens via `tokens_env`, default `SHUNT_CLIENT_TOKENS`, or `[[server.auth.jwt]]`) or `[server.gateway]` (gateway login) | [Reference](https://shunt.sh/reference/configuration/#serverusage-optional) |
- | Claude Code CLI native usage bars — serves `GET /api/oauth/usage` | `[server.oauth_usage]`, plus `[server.auth]` (client tokens via `tokens_env`, default `SHUNT_CLIENT_TOKENS`, or `[[server.auth.jwt]]`) or `[server.gateway]` on a non-loopback bind | [Reference](https://shunt.sh/reference/configuration/#serveroauth_usage-optional) |
- | Upstream status polling — Statuspage indicators as a metric, and in the dashboard on a `--features ui` build | `[server.status]` with at least one `[[server.status.sources]]` entry | [Reference](https://shunt.sh/reference/configuration/#serverstatus-optional) |
- | Bounded upstream retry — **on by default**, conservative, never mid-stream | `[providers.<name>.retry]` | [Reference](https://shunt.sh/reference/configuration/#providersnameretry) |
- | Shared-deployment limits — **on by default** (1024 concurrent, 32 MiB bodies, 120 s TTFB, device-flow rate limits); CIDR, header, and URL limits are opt-in | `[server] max_concurrent_requests`, `[server.access_control]`, `[server.limits]`, `[server.timeouts]`, `[server.rate_limits]` | [How-to](https://shunt.sh/guides/shared-gateway/) |
- | Secret references — `${VAR}` or `${file:/abs/path}` in any string value, re-resolved on hot reload (not `[sentry]`/`[otel]`, built once at startup — rotating those needs a restart) | any config string (**always on**) | [Reference](https://shunt.sh/reference/configuration/) |
- | Optional store — pool quota, gateway refresh tokens, and spend limits/audit in SQLite or PostgreSQL instead of the JSON snapshots; existing snapshots are imported once. One shunt process per store. The store holds refresh-token hashes: restrict database access and backups | `[store]` with `backend` and `url`; `backend = "postgres"` needs a `store-postgres` build (prebuilt release binaries have it; `cargo build` does not) | [Reference](https://shunt.sh/reference/configuration/#store-optional) |
- | OpenTelemetry metrics and traces | `[otel]` with a non-empty `endpoint` | [How-to](https://shunt.sh/guides/opentelemetry/) |
- ## Documentation
- Everything for users lives at **[shunt.sh](https://shunt.sh)**:
- - [Quickstart](https://shunt.sh/getting-started/quickstart/) · [Why shunt?](https://shunt.sh/getting-started/why-shunt/) · [Providers](https://shunt.sh/guides/providers/) · [Configuration](https://shunt.sh/guides/configuration/) · [Troubleshooting](https://shunt.sh/reference/troubleshooting/)
- - **For agents:** every page has a Markdown twin (append `.md` to any URL, or use the page's *Copy Markdown* / *Open in AI* buttons), and the site publishes [`/llms.txt`](https://shunt.sh/llms.txt), [`/llms-small.txt`](https://shunt.sh/llms-small.txt), and [`/llms-full.txt`](https://shunt.sh/llms-full.txt) per the [llms.txt spec](https://llmstxt.org/).
- Design notes and milestone specs for contributors live in [`docs/`](docs/) — start with [`docs/implementation-plan.md`](docs/implementation-plan.md).
- ## Why
- Claude Code sends every turn to the Anthropic API. `shunt` sits in front (via `ANTHROPIC_BASE_URL`) and, for the models you map, diverts their inference to another provider (OpenAI, Codex/ChatGPT, …). Because routing happens at the HTTP/inference layer — not by handing the task off to a different CLI — the session keeps running inside Claude Code's harness: same tool loop, same preloaded skills, same bundled-script path resolution. Only token generation is outsourced.
- Contrast with the alternative approach (handing a `subagent_type` off to another runtime like Codex CLI), which cuts higher in the stack and drops persona and preloaded skills.
- ### Per-model, not per-agent — and not a global swap
- Selectivity is driven by the **`model` id on each request**, which Claude Code already lets you choose per context: the `/model` picker for the main session, a subagent definition's `model:` frontmatter, `CLAUDE_CODE_SUBAGENT_MODEL` for all subagents, or `ANTHROPIC_CUSTOM_MODEL_OPTION` to add a custom entry to the picker. So "divert only this agent / this session" is decided in Claude Code, and shunt just honors the model id it receives — no fragile per-agent system-prompt fingerprinting. Unlike global model-swap proxies, the main session can stay on Claude while only the models you name divert.
- One model id can opt into deciding for itself. A [`[models.router]`](https://shunt.sh/guides/routing/) entry names a routing algorithm with a `type` key: `stage_router` picks per turn between a capable and an efficient target from the conversation's recent **tool-result metadata** — `tool_use.name` and `tool_result.is_error`, not prompt text — `auto` is that router under upstream's preset, `random` splits traffic across weighted targets and keeps a session on one arm, `noop` answers with an empty message for smoke tests, and `prefill_router` is a learned classifier over the latest user turn, available only from a build that opts into the off-by-default `prefill-router` cargo feature. Two types hand the decision to an **LLM judge**: [`llm_classifier`](https://shunt.sh/reference/configuration/#type--llm_classifier) routes on a verdict — `mode = "capability"` picks between a strong and a weak target on the judge's solve probability, `mode = "custom"` picks a model group named by your own prompt and JSON schema — and [`composite`](https://shunt.sh/reference/configuration/#type--composite) lets a judge set the tier a `stage_router` falls open to while leaving its signal scoring alone. Two more judge the **completed** turn before the client sees it: `llm_classifier` with [`mode = "escalation"`](https://shunt.sh/reference/configuration/#mode--escalation) serves a weak target's turn unless the judge keeps finding it in trouble, then latches the session onto a strong target, and [`advisor`](https://shunt.sh/reference/configuration/#type--advisor) has a stronger reviewer approve an executor's terminal turn or send it back to redo the work. Those turns are held until the verdict and then replayed, so the first byte arrives when the whole turn is done. A `stage_router` can also add an optional [`[models.router.classifier]`](https://shunt.sh/reference/configuration/#modelsrouterclassifier-optional) table naming a judge model, consulted only on the turns the signals leave undecided and never served to the client; a `classify_trigger` key decides when any of them consults a judge (`every_request`, `user_turn`, or `new_session`), and six `judge_*`/`gated_*`/`max_judge_calls` keys bound every internal call it makes. Every target is an ordinary public model id, so it keeps its own failover chain, pool, and adapter ([Routing overview](https://shunt.sh/guides/routing/)). Any entry can also carry a [`[models.subagents]`](https://shunt.sh/reference/configuration/#modelssubagents-optional) overlay that sends delegated work — `Task` sub-agents, hook agents, workflow sub-agents — to a different target, optionally per agent type (`by_type = { Explore = "claude-haiku-4-5" }`), while the parent session keeps its own destination; `main`, compaction, and auxiliary turns never take it. That overlay has a second form, [`type = "llm_classifier"` with `mode = "custom"`](https://shunt.sh/reference/configuration/#subagents-type--llm_classifier), which has a judge read the delegated task and pick the child's target once per (session, agent) — the parent is never classified. Configure neither a router nor a subagents overlay and nothing changes.
- ## Claude Code integration (official surface)
- Claude Code exposes a **first-class gateway contract** behind `ANTHROPIC_BASE_URL` — `shunt` implements this rather than the fragile "hash the subagent's system prompt" heuristic that earlier Claude Code proxies rely on.
- - [LLM Gateway Protocol](https://code.claude.com/docs/en/llm-gateway-protocol) — the API contract: endpoints, headers and body fields to forward vs consume, feature pass-through, and attribution. A running gateway serves the machine-readable spec at `GET /protocol`. Claude Code prepends a client-version and conversation fingerprint to the system prompt; shunt forwards that attribution block unchanged, since suppressing it is the developer's call via `CLAUDE_CODE_ATTRIBUTION_HEADER=0`. When it is suppressed, shunt restores the Claude Code identity on marker-less Claude Code requests sent with a subscription OAuth token to an Anthropic route (never on `count_tokens`), so side queries aren't rejected with the bare client-shape 429.
- - [Model discovery](https://code.claude.com/docs/en/llm-gateway-protocol#model-discovery) — Claude Code queries `GET /v1/models?limit=1000` at startup (opt-in via `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`) and adds returned models to the `/model` picker. shunt answers with curated `[[models]]` entries plus, while `auto_include_builtin_models` stays `true`, the caller's own live catalog — fetched only when `server.default_provider` is Anthropic-kind, and falling back to a built-in snapshot when it isn't, when no credential is available, or when the fetch fails. **Constraint:** entries whose `id` doesn't begin with `claude`/`anthropic` are ignored — non-Claude models must be aliased or added manually. See [Model discovery](https://shunt.sh/guides/model-discovery/).
- - **Gateway hint headers** (`CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`) — recent Claude Code releases describe each request with `x-claude-code-*` headers. shunt reads five of them into its routing context — the session id, the delegated-agent id, the request class (`main`, `subagent`, `workflow`, `compaction`, `auxiliary`), the agent type, and the one-shot flag marking the first turn after a context compaction — and `GET /protocol` lists them as consumed. The agent-id header is **not** gated by that variable, so on a default deployment a `Task` sub-agent already keeps its own [stage-router](https://shunt.sh/guides/stage-router/) tier pin, separate from the parent session's dwell and escalations, with no client change. Setting `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` on the client additionally sends the other four, which makes the request class authoritative over that agent-id fallback and lets the router hold the turns after a compaction on the capable tier.
- - [Add a custom model option](https://code.claude.com/docs/en/model-config#add-a-custom-model-option) — `ANTHROPIC_CUSTOM_MODEL_OPTION` adds a gateway-routed entry to the `/model` picker without replacing built-in aliases; the ID skips validation, so any string the gateway accepts works. **This is the primary way to select a non-Claude model** (e.g. `gpt-5.6-sol`), given the discovery constraint above.
- - **Tool search** (`ENABLE_TOOL_SEARCH`) — Claude Code defers MCP/LSP tool schemas and reveals them on demand, reclaiming context. Because shunt isn't a first-party Anthropic host, Claude Code keeps this **off** unless you opt in. Whether deferral then survives depends on the upstream, not on a setting alone: `claude*` and `anthropic/*` ids keep the protocol byte-for-byte, other ids have their `defer_loading` markers stripped because those hosts reject them, and the Responses path has its own three-state `tool_search` setting. See [Tool search](https://shunt.sh/guides/codex/#tool-search).
- - **Auto mode's server-side classifier** (`dangerous-tool-use-*`) — auto mode asks the API to classify each tool use server-side, at no charge. shunt relays the request and its verdict on Anthropic routes. Where the upstream cannot answer — a translated route, or an Anthropic-protocol third party, none of which is known to accept the field — shunt answers "could not evaluate" per action instead of returning nothing, so the client classifies just that action locally and keeps asking the server on the next turn rather than retiring the feature for the session. See [Troubleshooting](https://shunt.sh/reference/troubleshooting/).
- **Design principle:** be a spec-compliant Anthropic-Messages gateway (`/v1/messages`, `/v1/models`, correct header/attribution pass-through), route by the request's `model` id, and translate Anthropic Messages ⇄ the OpenAI Responses API for mapped models — no prompt-shape heuristics that break on every Claude Code prompt change. The opt-in stage router holds to the same line: it reads structured protocol fields, never the system prompt.
- ## Related work / prior art
- **Claude Code–specific routers & proxies**
- - [musistudio/claude-code-router](https://github.com/musistudio/claude-code-router) — the largest in this niche; use Claude Code as a foundation and decide how requests reach different models/providers.
- - [1rgs/claude-code-proxy](https://github.com/1rgs/claude-code-proxy) — run Claude Code on OpenAI models.
- - [fuergaosi233/claude-code-proxy](https://github.com/fuergaosi233/claude-code-proxy) — Claude Code → OpenAI API proxy.
- - [seifghazi/claude-code-proxy](https://github.com/seifghazi/claude-code-proxy) — captures/visualizes in-flight Claude Code requests, with optional **per-agent** routing to other providers (the direct inspiration for `shunt`'s subagent-routing idea).
- - [luohy15/y-router](https://github.com/luohy15/y-router) — a simple proxy enabling Claude Code to work with OpenRouter.
- - [tingxifa/claude_proxy](https://github.com/tingxifa/claude_proxy) — Cloudflare Workers proxy translating Claude API requests to OpenAI format (Gemini, Groq, Ollama).
- - [badlogic/claude-bridge](https://github.com/badlogic/claude-bridge) — use any model provider with Claude Code.
- - [jimmc414/claude_n_codex_api_proxy](https://github.com/jimmc414/claude_n_codex_api_proxy) — cross-runtime router: proxies Anthropic **or** OpenAI API calls to the local **Claude Code or Codex** CLI (routes to the local CLI when the API key is all 9s, else the real cloud API). Note the inverse direction — routing cloud-API calls *to* local CLIs, rather than routing Claude Code agents *out* to cloud providers.
- - [insightflo/chatgpt-codex-proxy](https://github.com/insightflo/chatgpt-codex-proxy) — Anthropic-compatible `/v1/messages` proxy that serves Claude Code inference from the **ChatGPT Codex backend** (uses a ChatGPT Plus/Pro subscription instead of an API key). Same inference-layer swap as `shunt`, targeting the Codex/GPT subscription backend while keeping Claude Code's UI and MCP tools.
- **General AI gateways (adjacent infrastructure — possible backends)**
- - [BerriAI/litellm](https://github.com/BerriAI/litellm) — SDK + proxy/AI gateway calling 100+ LLM APIs in OpenAI format, with cost tracking, guardrails, load balancing.
- - [Portkey-AI/gateway](https://github.com/Portkey-AI/gateway) — fast AI gateway routing to 1,600+ LLMs with integrated guardrails.
- - [maximhq/bifrost](https://github.com/maximhq/bifrost) — high-performance AI gateway with adaptive load balancing and 1000+ model support.
- - [mazori-ai/modelgate](https://github.com/mazori-ai/modelgate) — open-source LLM gateway + MCP server (Go): RBAC/policy enforcement, multi-provider (OpenAI, Anthropic, Gemini, Bedrock, Azure, and local Ollama), an MCP gateway with semantic tool search, and semantic response caching.
- ### How `shunt` differs
- Most Claude Code proxies above route **all** traffic to one alternative provider (a global model swap). `shunt`'s focus is **selective, per-model** diversion driven by the request's `model` id: keep the main session on Claude, and shunt only the models you name onto other providers — the switchboard/patchbay use case. Because Claude Code already lets you bind a model per context (main session, subagent `model:` frontmatter, `CLAUDE_CODE_SUBAGENT_MODEL`), that same selectivity reaches down to individual agents without shunt ever inspecting who the caller is.
- ## Contributing
- Issues and PRs are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md) for build/test commands and conventions, and [`SECURITY.md`](SECURITY.md) for reporting vulnerabilities.
- ### Code review
- Pull requests to `shunt` are reviewed by two AI code reviewers, both free for open source:
- - [Greptile](https://www.greptile.com/?utm_source=oss_badge&utm_medium=readme&utm_campaign=greptile_for_open_source) — free for non-commercial MIT/Apache projects under its OSS program.
- - [cubic](https://cubic.dev/) — free for public repositories.
- ## License
- Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or [MIT license](LICENSE-MIT) at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
- ---
- Made with Orca 🐋
- - https://github.com/stablyai/orca
- - https://www.onorca.dev/
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.