Discovered via unknown and last synced 3mo ago.
Install instructions not detected yet
Check the source repository for the latest setup steps.
ultra) ``` ### Config File (Enterprise) For teams with security policies blocking `.env` files: ```bash # Create secure config file llm-router init-config # Edit ~/.llm-router/config.yaml openai_api_key: "sk-proj-..." gemini_api_key: "AIza..." ollama_base_url: "http://localhost:11434" llm_router_profile: "balanced" ``` Set permissions: `chmod 600 ~/.llm-router/config.yaml` For full setup guide, see **[docs/SETUP.md](docs/SETUP.md)**. --- ## Monitoring & Optimization ### Real-Time Session Metrics ```bash # Show savings from current session llm-router usage today # Show all usage data (weekly breakdown) llm-router usage week # Show cost efficiency over time llm-router savings # Check current quota pressure llm-router budget ``` ### Identify Optimization Opportunities ```bash # Analyze routing decisions and find inefficiencies python3 scripts/analyze-violations.py # → Shows which sessions violated routing hints # → Identifies patterns (e.g., Bash used when llm_query should route) # Analyze hook health llm-router health # → Model quality scores, provider status, circuit breaker state ``` ### Preventing Routing Violations **Violation:** Ignoring a `⚡ MANDATORY ROUTE` hint (costs extra tokens with zero savings). **Example violation:** ``` ⚡ MANDATORY ROUTE: query/simple → call llm_query ❌ User/Claude uses Bash instead → burns expensive Claude tokens ``` **Enforcement modes:** ```bash LLM_ROUTER_ENFORCE=smart # (default) Hard block Q&A violations, soft block code LLM_ROUTER_ENFORCE=hard # Block all violations (strictest, best savings) LLM_ROUTER_ENFORCE=soft # Log violations, allow calls (permissive) LLM_ROUTER_ENFORCE=off # No enforcement (max flexibility) ``` **Sessions with 3+ violations** get a warning: ``` ⚠️ ESCALATION: 5 routing violations this session. Next prompt should call llm_query FIRST before any Bash/Read/Edit. Set LLM_ROUTER_ENFORCE=hard to block violations automatically. ``` For detailed guidance, see **[Monitoring & Reducing Violations](README.md#monitoring--optimization)** in CLAUDE.md. --- ## What's New in Recent Releases ### v7.6.0 — Agent Resource Budgeting (Latest) **Complete budget management for Agent calls with provisional tracking.** - **Session Budget Allocation** — Smart carving: 30% of remaining quota per session, $5–$50 range - **Provisional Spend Tracking** — Real-time budget decrements prevent multiple agents from thinking budget is available - **Budget Reconciliation** — On failure: refund 50% (only pay for delivered value) - **Hard Limits** — $5/agent, $50/session (fallback safety valve) Example: ``` Session → $5 budget allocated Agent 1 (code) → -$1.00 → $4 remaining Agent 2 (code) → -$1.00 → $3 remaining Agent 1 succeeds → keep deduction Agent 2 times out → refund $0.50 → $3.50 remaining ``` See [Agent Resource Budgeting](CLAUDE.md#agent-resource-budgeting) for detailed setup. ### v7.4.0 — Content Generation Routing Discipline **Automatic detection of writing tasks with decomposition guidance.** - **Smart Detection** — Recognizes "write", "draft", "add card", "create spec" patterns - **Decomposition** — Suggests: route generation → integrate locally (saves 90% on writing) - **Soft Nudges** — Hook suggests routing without blocking Example suggestion: ``` ⚡ SUGGESTION: This looks like content generation. Consider: llm_generate() first, then Edit/Write to integrate. Saves ~$0.0005, follows best-practice decomposition. ``` ### v7.0.0 — Free-First Chain & Ollama Auto-Startup **Optimized routing chains with automatic local inference.** - **Ollama Auto-Startup** — Session-start hook launches Ollama + loads budget models if not running - **Free-First Chains** — Ollama → Codex → Gemini → OpenAI → Claude (all complexity levels) - **Codex as Free Fallback** — Injected before all paid models when subscription available - **Routing Analytics** — Track which model selected, cost impact, complexity distribution See [CHANGELOG.md](CHANGELOG.md) for complete v6.x history. --- ## MCP Tools Reference (48 Total) ### Routing & Classification
off export LLM_ROUTER_MAX_AGENT_DEPTH=3 # Circuit breaker for nested agents # Advanced export LLM_ROUTER_DB_PATH="~/.llm-router/usage.db" # Where to store usage logs export LLM_ROUTER_CAVEMAN_INTENSITY="full" # Compress output tokens (off
Deep analysis (Sonnet-class reasoning)
List available pipeline templates
Interactive provider setup guide
Host-agnostic routing wrapper (savings tracking)
Manually log token usage for budget tracking
Generate images (Gemini/DALL-E/Flux)
Real-time budget pressure (0.0–1.0)
Refresh Claude subscription quota data
Multi-file edits with cheap model reasoning
Generate videos (Gemini Veo/Runway)
Provider health status & circuit breaker state
Update usage cache from API response
Build workspace context for routing
Route task to optimal model by complexity/profile
Multi-file code edits with reasoning
Show cost breakdown (today/week/month/all)
Judge scores & quality trends
Find files by description
Classify task complexity: simple/moderate/complex
Cost savings vs Opus baseline
Archive session for cross-session learning
Generate bulk rename commands
Purpose
Research with web access (Perplexity)
Switch routing profile (budget/balanced/premium)
No personalization
premium export LLM_ROUTER_ENFORCE="smart" # smart
Create content (Flash-class, cheap)
Multi-step pipelines (research → analysis → generation)
Route directly to Codex (prepaid OpenAI subscription)
Answer questions (Haiku-class models, fast)
Generate speech (ElevenLabs/OpenAI TTS)
List configured providers & API key status
Auto-refresh Claude quota (OAuth)
llm-router
Code generation & refactoring (Sonnet → Opus)
View/manage routing policies
Route directly to Gemini CLI