shunt Wiki

shunt is a Rust Claude Code LLM gateway that exposes the Anthropic Messages gateway surface, routes by request model, passes unmapped models through to Anthropic, and translates mapped OpenAI-family models to the OpenAI Responses API. The CLI starts an Axum server, the router chooses a provider from TOML/env configuration, adapters either stream pass-through bytes or translate Responses SSE, and auth helpers resolve OpenAI, ChatGPT/Codex, and Claude gateway credentials src/main.rs:38-76 src/server.rs:13-25 src/routing.rs:37-89 src/adapters/responses.rs:34-213.

Quick Start

Step	Command	Expected result	Source
Build	cargo build --release	target/release/shunt is produced	docs/running.md:26-37
Create config	cp shunt.toml.example shunt.toml	Local editable TOML config	docs/running.md:40-55
Validate config	./target/release/shunt check	Prints config ok or a typed error	src/main.rs:77-83
Run gateway	./target/release/shunt run	Logs shunt listening	src/main.rs:38-76
Connect Claude Code	export ANTHROPIC_BASE_URL=http://127.0.0.1:3001	Claude Code sends gateway traffic locally	docs/running.md:189-393

flowchart LR
    CC[Claude Code] -->|ANTHROPIC_BASE_URL| S[shunt Axum gateway]
    S --> R{Route by model}
    R -->|unmapped| A[Anthropic Messages passthrough]
    R -->|mapped responses provider| O[OpenAI Responses translation]
    O --> C[OpenAI or ChatGPT Codex backend]
    A --> API[api.anthropic.com or compatible gateway]
    classDef dark fill:#2d333b,stroke:#6d5dfc,color:#e6edf3;
    class CC,S,R,A,O,C,API dark;
    linkStyle default stroke:#8b949e;

Documentation Map

Section	Purpose	Start here when…
Onboarding	Audience-specific guides for contributors, staff engineers, executives, and PMs	You are new to the project
Getting Started	Product overview, setup, config, and operations	You want to run or configure shunt
Deep Dive	Architecture, routing, adapters, auth, and testing	You need to modify internals

Key Files

File	Responsibility	Source
src/main.rs	CLI, tracing, run, check, and token commands	src/main.rs:38-76
src/server.rs	Axum router and shared AppState	src/server.rs:13-25
src/proxy.rs	Request buffering, routing, adapter dispatch, logging	src/proxy.rs:19-126
src/routing.rs	Exact route, prefix route, default-provider resolution	src/routing.rs:37-89
src/config.rs	Typed config, defaults, figment TOML/env loading, validation	src/config.rs:9-269
src/adapters/anthropic.rs	Pass-through Anthropic-compatible adapter	src/adapters/anthropic.rs:31-104
src/adapters/responses.rs	OpenAI Responses transport and streaming response conversion	src/adapters/responses.rs:34-213
src/model/responses_request.rs	Anthropic request to Responses request translation	src/model/responses_request.rs:4-280
src/model/responses.rs	Responses SSE to Anthropic SSE state machine	src/model/responses.rs:45-378
src/auth/*	Provider credential resolution and token refresh helpers	src/auth/mod.rs:29-99

Tech Stack Summary

Layer	Technology	Why it exists	Source
CLI	clap	Provides run, check, and token command surface	src/main.rs:7-35
HTTP server	Axum	Serves Claude Code gateway endpoints and streams bodies	src/server.rs:13-25
Async runtime	Tokio	Drives server and HTTP client futures	Cargo.toml:1-23
HTTP client	Reqwest with rustls-tls and stream	Streams upstream responses without OpenSSL	Cargo.toml:1-23
Config	Figment + TOML + env	Merges defaults, file config, and SHUNT_ overrides	src/config.rs:185-194
Observability	Tracing	Logs per-request span fields and latency	src/proxy.rs:26-60
Tests	Wiremock + Tokio tests	Exercises gateway endpoints and translation behavior	tests/passthrough.rs:72-247

Related Pages

Page	Relationship
Overview	Explains the gateway problem shunt solves
Configuration	Shows provider and route setup
Architecture	Maps the runtime components and invariants
Adapters and Translation	Details the pass-through and Responses adapters