Project Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• ARCHITECTURE.md
• llms.txt
• AGENTS.md
• CONTRIBUTING.md
• blueprints/provider/_generic.md

shunt (crate shunt-gateway) is a specialized technical gateway designed to act as a transparent proxy for Claude Code. Its primary purpose is to intercept Anthropic-style Messages API requests and, based on user-defined configuration, route specific model identifiers to alternative LLM providers like OpenAI, xAI, or Cursor, while passing all other traffic through to Anthropic unchanged.

The system is built to preserve the rich feature set of Claude Code—including tool usage, skills, and streaming—even when the underlying inference is performed by a different model provider. It is implemented in Rust and focuses on high performance, streaming integrity, and hot-swappable configuration.

Sources: ARCHITECTURE.md:5-10, llms.txt:1-3, AGENTS.md:33-43

Core Architecture

The project follows a layered architecture where dispatch logic flows downward, ensuring that lower infrastructure layers remain decoupled from upper-level routing and serving policies.

Dependency Layers

The system is organized into four primary layers:

1. Interface Layer: Handles CLI subcommands (via main.rs) and HTTP endpoint registration using the Axum router (server.rs).
2. Application Layer: Manages the request pipeline, including body buffering, inbound authentication, and route resolution (proxy.rs, routing.rs).
3. Domain Layer: Contains provider-specific adapters and protocol translation logic (Anthropic ⇄ OpenAI) found in src/adapters/ and src/model/.
4. Infrastructure Layer: Provides foundational services such as configuration loading, authentication helpers, telemetry, and hot reloading (config.rs, auth/, reload.rs).

Sources: ARCHITECTURE.md:23-42, AGENTS.md:21-31

Request Flow Diagram

The following diagram illustrates the lifecycle of a request as it moves through the shunt gateway.

Key Components and Modules

shunt utilizes several specialized modules to handle the complexities of multi-provider proxying and protocol translation.

Primary Modules Reference

Module	Purpose	Key Responsibility
server	Axum Router	Manages HTTP endpoints and AppState snapshots.
proxy	Pipeline Manager	Handles buffering, auth gating, and adapter dispatch.
routing	Model Resolver	Maps model IDs (exact or prefix) to specific routes.
adapters	Provider Interface	Implements the Adapter trait for specific protocols.
model	Translation	Converts Anthropic Messages to OpenAI Responses and back.
config	Typed Config	Handles TOML/env loading and hot-reload logic.
auth	Credentials	Manages per-provider lookup and refresh flows.

Sources: ARCHITECTURE.md:66-82, AGENTS.md:21-31

Architecture Invariants

To maintain compatibility and performance, the system adheres to several strict invariants:

• Streaming Integrity: Upstream SSE responses are forwarded unbuffered unless the client explicitly requests non-streaming output.
• Error Reshaping: All gateway-owned errors are transformed into the Anthropic error envelope ({"type":"error", ...}) to ensure Claude Code compatibility.
• Configuration Snapshots: State is snapshotted once per request using arc-swap, ensuring mid-request reloads do not cause inconsistent behavior.
• Table-Driven Logic: Adding new providers or models is primarily done through configuration rather than code changes.

Sources: ARCHITECTURE.md:95-115, AGENTS.md:45-53

Supported Providers and Adapters

The system maps different upstream providers to specific AdapterKind implementations.

Provider	Adapter Kind	Auth Mechanism
anthropic	Anthropic	Passthrough / OAuth
openai	Responses	API Key
codex	Responses	ChatGPT OAuth (WS v2)
xai	Responses	API Key
cursor	Cursor	Cursor OAuth

Sources: ARCHITECTURE.md:86-93

Development and Operations

shunt is a Rust-based project (Edition 2021) that utilizes cargo for its lifecycle management.

Build and Test Commands

# Build the project
cargo build

# Run the gateway
cargo run -- run

# Validate configuration files
cargo run -- check

# Run the full test suite
cargo test --all-features --workspace

Sources: AGENTS.md:5-15, CONTRIBUTING.md:7-12

Configuration Management

The gateway supports hot reloading of configurations. A background task watches for changes in the TOML/YAML configuration files and swaps the internal state without requiring a process restart. This allows operators to update routes or credentials dynamically.

Sources: ARCHITECTURE.md:133-138, ARCHITECTURE.md:113-115

Conclusion

shunt serves as a critical bridge for developers using Claude Code who require flexibility in their choice of LLM backends. By providing a high-performance Rust implementation that prioritizes streaming and protocol fidelity, it allows for seamless integration of diverse models while maintaining a consistent interface for the Claude Code toolset.