Claudex Fallback Model Path & Inference Architecture¶

1. Role & Authority Boundary¶

Claudex is the inference fallback proxy for the Claude Code execution harness. It is never a work, source, or doctrine authority.

THOMAS (Operator / Intent)
   │
   ├─► NORMAL PATH:  `claude`   ──► Anthropic API (Primary Sonnet / Opus)
   │
   └─► FALLBACK PATH: `claudex` ──► StringKe Claudex Proxy (127.0.0.1:13456)
                                      ├── Protocol Translation: Anthropic <-> OpenAI API
                                      ├── Model Slot Mapping: Haiku / Sonnet / Opus
                                      │
                                      ├── Tier 1: Synology NAS Ollama (http://blueflynas:11434/v1)
                                      │     ├── `qwen3-coder:30b` (Heavy implementation)
                                      │     ├── `qwen2.5-coder:7b` (Normal coding)
                                      │     └── `phi4-mini` (Lightweight / fast)
                                      │
                                      ├── Tier 2: Mac M4 Local Ollama (http://127.0.0.1:11434/v1)
                                      │     ├── `qwen3-coder:30b`
                                      │     ├── `qwen3:8b` / `qwen3:14b`
                                      │     └── `qwen2.5-coder:3b`
                                      │
                                      └── Tier 3: Local LM Studio (http://localhost:1234/v1)

Context & Harness Continuity:¶

Both claude (normal) and claudex (fallback) execute the identical Claude Code harness: - AGENTS.md context bootstrap - .agents/skills/ skill store - .mcp.json / MCP tool definitions - Active Git worktree & branch - Gas City (bd / gc) task tracking - GitLab (glab) release workflow

2. Implementation Evaluation & Candidate Comparison¶

Evaluation Metric	`StringKe/claudex` (Selected)	Ollama Direct (`ANTHROPIC_BASE_URL`)	`alexgetmancom/claudex` (Avoided)
Protocol Translation	Full Anthropic <-> OpenAI SSE translation	Anthropic native (experimental)	Translation proxy
Model Slot Mapping	Configurable `haiku`/`sonnet`/`opus` slots	Unrecognized model warning/hang	Fixed mapping
Multi-Provider Failover	Configurable backup providers	Single endpoint only	None
Tool Calling / Streaming	Full SSE streaming + function calls	Basic completions	Tool failures reported
Terms / Account Risk	Local loopback, no credential spoofing	Local loopback	Documented account suspension warnings
Binary / Runtime	Single compiled Rust binary (`v0.2.4`)	Built into Ollama	Node / NPM wrapper

3. Model Slot Mapping Matrix¶

Slot	Target Model	Provider / Tier	Typical Workload
HAIKU	`phi4-mini` / `qwen2.5-coder:3b`	NAS / Local Mac	Fast exploration, metadata extraction, small fixes
SONNET	`qwen2.5-coder:7b` / `qwen3:8b`	NAS / Local Mac	Core coding, git workflows, review, verification
OPUS	`qwen3-coder:30b`	NAS / Local Mac	Complex multi-file refactoring, platform architecture

4. Fallback Trigger Doctrine¶

Fallback to claudex should occur strictly under legitimate quota or connectivity events: - RATE_LIMIT / USAGE_QUOTA: Anthropic tier usage limit reached -> Switch to claudex. - SERVICE_FAILURE / NETWORK_FAILURE: Anthropic API outage -> Switch to claudex. - POLICY / AUTH ERRORS: Do NOT hide credential errors behind silent fallback. Fix auth before resuming.

5. Portability & Configuration Governance (GOV-PATH-PRIV-001)¶

Runtime Configuration: ~/.config/claudex/config.toml (auto-discovered).
Executable Dispatcher: ~/.local/bin/claudex -> ~/.local/bin/claudex-bin.
Zero Workstation Absolute Paths: All paths use ~, $HOME, or environment variables.
Secrets Governance: No API keys stored in plaintext; local Ollama requires no secret (ollama).