Executive Guide

System Overview

shunt lets a Claude Code user keep the Claude Code workflow while selectively sending chosen model IDs to another model provider. This preserves developer productivity tooling while creating optionality across model vendors README.md:1-60 docs/running.md:1-461.

Capability	Status	Maturity	Dependency	Source
Local gateway for Claude Code	Built	Working implementation	Axum/Rust binary	src/server.rs:13-25 src/main.rs:38-76
Anthropic pass-through	Built	Tested	Anthropic-compatible upstream	src/adapters/anthropic.rs:31-104 tests/passthrough.rs:72-247
OpenAI Responses translation	Built	Tested with fixtures	OpenAI Responses API shape	src/adapters/responses.rs:34-213 tests/responses_translate.rs:25-287
ChatGPT/Codex credential reuse	Built	Sensitive; needs operational care	`~/.codex/auth.json`	src/auth/codex_auth.rs:34-63
Model discovery	Built	Limited by Claude Code ID rules	Claude Code gateway discovery	src/discovery.rs:17-30 docs/running.md:189-393
Production hardening	Partial	Roadmap item	Observability/timeouts/retries	docs/implementation-plan.md:6-249

graph LR
    Dev[Developer] --> Claude[Claude Code]
    Claude --> Shunt[Local shunt gateway]
    Shunt --> Anthropic[Anthropic]
    Shunt --> OpenAI[OpenAI]
    Shunt --> ChatGPT[ChatGPT Codex]
    classDef dark fill:#2d333b,stroke:#6d5dfc,color:#e6edf3;
    class Dev,Claude,Shunt,Anthropic,OpenAI,ChatGPT dark;
    linkStyle default stroke:#8b949e;

Technology Investment Thesis

Technology	Purpose	Risk level	Investment view	Source
Rust + Tokio	Reliable local network service	Low	Good fit for streaming gateway	Cargo.toml:1-23
Axum	HTTP routing and serving	Low	Simple implementation surface	src/server.rs:13-25
Reqwest streaming	Upstream calls and SSE relay	Medium	Critical for responsiveness	src/adapters/anthropic.rs:31-104
Figment TOML/env	Operator configuration	Low	Reduces code churn for providers	src/config.rs:185-194
Token-file reuse	Fast setup for Codex/ChatGPT	Medium	Practical but security-sensitive	src/auth/codex_auth.rs:34-63 SECURITY.md:1-38

Risk Assessment

Risk	Likelihood	Impact	Mitigation	Owner
Provider API shape changes	Medium	High	Keep translation tests and fixtures current	Engineering
Credential refresh failure	Medium	Medium	Surface clear `codex login` errors and prefer setup tokens where possible	Engineering/Users
Streaming regression	Low	High	Wiremock and SSE state machine tests	Engineering
Discovery confusion	Medium	Low	Document custom model option and aliases	Developer Experience
Private early status	High	Medium	Keep docs explicit and avoid over-promising	Maintainers

graph TB
    Shunt[shunt] --> Anthropic[Anthropic-compatible providers]
    Shunt --> OpenAI[OpenAI Platform]
    Shunt --> Codex[ChatGPT Codex backend]
    Shunt --> Files[Local credential files]
    Files --> Risk[Credential handling risk]
    classDef dark fill:#2d333b,stroke:#6d5dfc,color:#e6edf3;
    class Shunt,Anthropic,OpenAI,Codex,Files,Risk dark;
    linkStyle default stroke:#8b949e;

Cost and Scaling Model

Driver	Cost behavior	Current bottleneck	Source
Local CPU/memory	Minimal; proxy and translation only	JSON/SSE transformation in process	src/model/responses_request.rs:4-280 src/model/responses.rs:45-378
Upstream inference	Scales with selected provider usage	Provider account limits and entitlements	docs/running.md:189-393
Developer operations	One local process per user or environment	Credential setup and config correctness	docs/running.md:1-461

Roadmap Alignment

flowchart LR
    M0[M0 pass-through] --> M1[M1 Responses translation]
    M1 --> M2[M2 ChatGPT OAuth]
    M2 --> M3[M3 discovery UX]
    M3 --> M4[M4 hardening]
    classDef dark fill:#2d333b,stroke:#6d5dfc,color:#e6edf3;
    class M0,M1,M2,M3,M4 dark;
    linkStyle default stroke:#8b949e;

Recommendations

Priority	Recommendation	Expected impact	Source
1	Keep translation tests as release gate	Protects core compatibility	tests/responses_translate.rs:25-287 .github/workflows/ci.yml:1-42
2	Document supported provider/model combinations continuously	Reduces setup failures	docs/running.md:1-461 shunt.toml.example:1-134
3	Add production-hardening backlog around timeouts/retries/observability	Improves reliability if shared beyond local use	docs/implementation-plan.md:6-249
4	Treat credential-file refresh as a security-sensitive area	Reduces incident risk	SECURITY.md:1-38 src/auth/codex_auth.rs:34-63

Page	Relationship
Product Manager Guide	Product-facing explanation
Staff Engineer Guide	Architectural details
Operations	Current operating model