Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
shunt is a spec-compliant Claude Code LLM gateway designed to act as a transparent Anthropic-Messages proxy. Its primary purpose is to allow developers using Claude Code to divert inference to alternative providers—such as OpenAI, ChatGPT/Codex, xAI, or any Anthropic-compatible backend—while preserving tools, skills, and streaming functionality.
The gateway operates by intercepting Anthropic protocol requests and routing them based on model identifiers defined in the configuration. For unmapped traffic, it ensures a seamless pass-through to Anthropic's native API, maintaining the integrity of the Claude Code harness.
Sources: ARCHITECTURE.md:6-12, README.md
Quickstart and Installation
To get started with shunt, ensure you have a Rust development environment (stable, edition 2021) installed. The project uses standard Cargo commands for building and running.
Build Commands
| Action | Command |
|---|---|
| Build project | cargo build |
| Release build | cargo build --release |
| Run gateway | cargo run -- run |
| Validate config | cargo run -- check |
| Generate token | cargo run -- token |
Sources: AGENTS.md:5-10, CONTRIBUTING.md:10-15
Installation via Homebrew
For macOS and Linux users, a Homebrew formula is available. Shunt can be installed as a binary corresponding to the system architecture (e.g., darwin-arm64, linux-x64).
Sources: packaging/homebrew/shunt.rb:10-25
Configuration Management
The gateway relies on a configuration file (typically shunt.toml or shunt.yaml) to define routing logic, provider details, and authentication credentials. Shunt probes several locations for this file, starting from the current directory to standard config paths like $XDG_CONFIG_HOME/shunt/.
Configuration Validation
Before running the server, it is critical to validate the configuration to ensure there are no mismatched provider kinds or malformed account definitions.
shunt check
Sources: blueprints/upstream/_generic.md:24-30, ARCHITECTURE.md:126-130
Routing Architecture
Routing is handled through three distinct mechanisms:
- Exact Routes: Matches specific model IDs.
- Prefix Routes: Matches model IDs starting with a specific string.
- Default Provider: Falls back to a default provider (usually Anthropic) if no other routes match.
The following diagram illustrates the request flow and routing logic:
This diagram shows the path of a request from the client through the proxy routing logic to the upstream provider.
Sources: ARCHITECTURE.md:14-23, src/AGENTS.md:15-22
Supported Providers and Adapters
Shunt uses specialized adapters to translate protocols between the Anthropic Messages format and various upstream APIs.
Adapter Matrix
| Provider | Adapter Kind | Purpose |
|---|---|---|
| Anthropic | anthropic | Native passthrough or OAuth |
| OpenAI | responses | Translation to OpenAI Responses API |
| xAI / Grok | responses | Translation for xAI subscription APIs |
| ChatGPT | responses | Includes WebSocket v2 transport for Codex |
| Cursor | cursor | ConnectRPC/protobuf protocol translation |
Sources: ARCHITECTURE.md:67-78, blueprints/provider/_generic.md:18-24
Development Environment Setup
For contributors, the project enforces strict code quality standards including formatting, linting, and comprehensive testing.
Testing and Quality Gates
All contributors must pass the following checks before submitting a Pull Request:
- Formatting:
cargo fmt --all --check - Linting:
cargo clippy --all-targets --all-features -- -D warnings - Unit/Integration Tests:
cargo test --all-features --workspace
Sources: CONTRIBUTING.md:17-21, AGENTS.md:15-18
Documentation Structure
The project maintains multiple documentation surfaces that must stay synchronized with code changes:
README.md: Overview and quickstart.site/: The official documentation site (Nimbus-based).wiki/: An Astro Starlight-based wiki (generated, do not hand-edit).llms.txt: LLM-readable documentation map.
Sources: wiki/AGENTS.md:18-24, AGENTS.md:43-52, site/README.md:10-15
Conclusion
Setting up shunt involves building the Rust binary, configuring providers via shunt.toml, and validating the setup using the check command. By following the routing and adapter patterns, operators can effectively redirect Claude Code traffic to alternative LLM backends while maintaining full protocol compatibility and streaming performance.