Architecture Overview

Relevant source files

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

• ARCHITECTURE.md
• AGENTS.md
• src/AGENTS.md
• blueprints/provider/_generic.md
• CONTRIBUTING.md

shunt (crate shunt-gateway) is a spec-compliant Claude Code LLM gateway designed to act as a transparent Anthropic-Messages proxy. Its primary purpose is to allow developers to use the Claude Code interface while diverting specific model inference requests to alternative providers such as OpenAI, xAI, Grok, or Cursor. Unmapped traffic is passed through to Anthropic unchanged, ensuring full compatibility with the Claude Code LLM gateway protocol.

The system is optimized for high-performance developer workflows, prioritizing the preservation of streaming semantics (Server-Sent Events) and maintaining a strict Anthropic-compatible error envelope. It is designed to be highly configurable, allowing for the addition of new providers and models through table-driven configuration rather than hardcoded logic.

Sources: ARCHITECTURE.md:1-12, blueprints/provider/_generic.md:21-25

System Structure and Dependency Layers

The project follows a layered architecture where dispatch flows downward. Lower layers are decoupled from the routing and serving policies defined in upper layers.

Core Request Pipeline

The "hot path" for request proxying involves several stages: buffering, routing, authentication, and dispatch. This flow ensures that requests are correctly identified and transformed before reaching the upstream provider.

Request Flow Stages

1. Ingress & Buffering: server.rs routes the inbound HTTP request to proxy::forward. The request body is buffered to allow for model identification and potential protocol translation.
2. Route Resolution: The routing::resolve function inspects the model ID. It follows a hierarchy: Exact Route → Prefix Route → default_provider.
3. Adapter Dispatch: Based on the resolved Route, an AdapterKind is selected. The adapter handles provider-specific authentication injection and protocol translation (e.g., Anthropic to OpenAI).
4. Streaming Response: The upstream response is streamed back to the client unbuffered (unless non-streaming was explicitly requested).

Components and Modules

Component	Responsibility	Key Files
Server	Axum router, endpoint registration, and state snapshots.	src/server.rs
Proxy	The main pipeline: buffering, routing, and adapter dispatch.	src/proxy.rs
Routing	Maps model IDs to routes, including stripping [1m] suffixes.	src/routing.rs
Adapters	Provider-specific protocol implementations (Anthropic, Responses, Cursor).	src/adapters/
Model	Translation logic between Anthropic Messages and OpenAI Responses.	src/model/
Auth	Manages provider credentials, token refreshes, and inbound client auth.	src/auth/
Config	Typed TOML/YAML configuration and hot-reloading.	src/config.rs, src/reload.rs

Sources: ARCHITECTURE.md:58-75, AGENTS.md:16-25

Architecture Invariants

The system maintains several critical invariants to ensure stability and compatibility:

• Streaming Integrity: Upstream SSE (Server-Sent Events) are never buffered. Violating this breaks incremental rendering in Claude Code.
• Error Reshaping: All gateway-owned errors are transformed into the Anthropic error shape (type/message envelope).
• Configuration over Code: New models and providers are added via [[routes]] or [providers] config entries rather than hardcoded logic.
• Request Snapshots: Configuration is snapshotted once per request via SharedState (arc-swap). Mid-request configuration reloads do not affect in-flight requests.
• Unmapped Passthrough: Any request that does not match a specific route defaults to the anthropic provider.

Sources: ARCHITECTURE.md:86-110, blueprints/provider/_generic.md:46-51

Protocol Adapters

Adapters implement the Adapter trait to handle communication with different LLM backends.

Provider	Adapter Kind	Upstream Protocol
Anthropic	Anthropic	Native Anthropic Messages
OpenAI	Responses	OpenAI Responses API
Codex	Responses	WebSocket v2 / ChatGPT Backend
xAI / Grok	Responses	xAI API (OpenAI-compatible)
Cursor	Cursor	Cursor ConnectRPC/protobuf

Sources: ARCHITECTURE.md:77-84, blueprints/provider/_generic.md:16-20

Conclusion

The shunt architecture provides a robust, high-performance gateway for Claude Code by leveraging a layered Rust implementation. By prioritizing streaming semantics and strict protocol conformance, it allows developers to swap LLM backends transparently while maintaining the features and safety of the Claude Code environment.

Sources: ARCHITECTURE.md:1-5, ARCHITECTURE.md:118-125