llms.txt

# clutch - Provider-Neutral LLM Orchestration Engine

Last-checked: 2026-08-16
Test-suite: 314 passing unit tests (pytest verified 100% green)

> clutch (German: Kupplung) uses a driving metaphor to intelligently route tasks to optimal LLM models across providers. It analyzes task complexity, selects the right model and reasoning level, tracks budgets with a four-zone fuel gauge, and learns from experience via fitness scoring and epsilon-greedy exploration.

clutch is the routing layer of the ellmos family (Extra Large Language Model Operating Systems): a provider-neutral orchestration engine that sits in front of Anthropic (Claude), Google (Gemini), Ollama (local), Claude Code, agy through companion-for-agy, and Kimi/Moonshot. Every concept is mapped onto a car metaphor -- Fahrer (driver/orchestrator), Getriebe (gearbox/model registry, gears G1-G5 from Haiku to Opus), Gas/Bremse (throttle, reasoning level 0-100%), Kupplung (clutch, model switching), Tankuhr (fuel gauge, budget tracking), Fahrtenbuch (trip log, SQLite metrics), Fahrschule (learning engine). Current version v0.4.0 (library + CLI + optional FastAPI web UI; purpose- and vision-aware routing; model discovery; credential store; i18n en/de/es/zh/ja/ru). Python 3.10+, MIT. Verified 314/314 passing unit tests.

Gemini flash tier (2026-08-13): the preferred Google gear is `gemini-3.7-flash` (G2, 1M context, thinking levels low/medium/high recorded in the catalog); the older `gemini-3.5-flash` gear stays available as fallback. Gemini 3.7 is a Google-API gear only -- the agy/companion-for-agy rail still tops out at `gemini-3.6-flash`, which that CLI build offers.

Execution patterns: single (one task), convoy (chain), team (parallel workers), swarm (bulk). Road types classify tasks by difficulty: Feldweg (trivial, Haiku), Landstrasse (standard, Sonnet), Autobahn (architecture, Opus), Rallye (bulk, Haiku swarm), Konvoi (pipeline, Sonnet chain), Langstrecke (complex, Opus hybrid). Budget tracking uses four zones: green / yellow / orange / red with daily and monthly limits. Circuit breakers, latency tracking, and provider failover are built in (Bordcomputer).

## Docs

- [README](https://github.com/ellmos-ai/clutch/blob/master/README.md): Overview, architecture, road types, installation, quickstart
- [GLOSSARY](https://github.com/ellmos-ai/clutch/blob/master/GLOSSARY.md): German automotive code terms mapped to English
- [LICENSE](https://github.com/ellmos-ai/clutch/blob/master/LICENSE): MIT license text

## Audience

- Developers building provider-neutral LLM routing layers
- Agent-framework maintainers who need model selection, budget limits, and failover
- Local-first AI operators combining Anthropic, Gemini, Ollama, and Claude Code
- Researchers comparing orchestration patterns such as chains, teams, swarms, and hybrids

## Search Phrases

- ellmos-ai clutch provider neutral LLM router
- clutch LLM orchestration engine auto learning
- Python model routing Anthropic Gemini Ollama Claude Code
- local-first LLM budget tracking circuit breaker
- agent framework chain team swarm orchestration
- German automotive metaphor LLM routing

## ellmos family (related projects)

- [USMC](https://github.com/ellmos-ai/usmc): Shared memory primitive (Tier 1)
- [Rinnsal](https://github.com/ellmos-ai/rinnsal): Lightweight agent infrastructure (Tier 2)
- [BACH](https://github.com/ellmos-ai/bach): Full text-based OS for LLMs (Tier 3)
- [Gardener](https://github.com/ellmos-ai/gardener): Database-based OS counterpart
- [MarbleRun / llmauto](https://github.com/ellmos-ai/MarbleRun): Chain-execution framework
- [Skills](https://github.com/ellmos-ai/skills): Portable skill library

## Optional

- [GitHub Issues](https://github.com/ellmos-ai/clutch/issues): Bug reports and feature requests