autonomous-ai-agency / router
CLAUDE.md12 starsChanged 29 days agoMITView on GitHub
Model routing affects every request in the system. The invariants you must not break are CLAUDE.md rules 21–23. Read those first. This file covers how selection works and how to extend it. The central model-selection layer for all API surfaces. Selection priority, highest first: Local Ollama model names are passthrough: they bypass the alias table entirely and resolve to RoutingDecision(selection_source="passthrough"). The health check is cached with TTL ROUTER_HEALTH_CACHE_TTL (default 60s). The cache is deliberately invalidated before fallback retries — that…
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.md
- agent/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/verification.mdcCursor rule
- agentic-agileSkill
- agentic-portfolioSkill
- client-onboardingSkill
- cooldown-resumeSkill
- drillSkill
- ecc-harness-patternsSkill
- fabric-patternsSkill
- graphiti-temporalSkill
- managed-agents-dreamsSkill
- model-catalogue-updateSkill
- platform-setupSkill
- repowise-intelligenceSkill
- risky-module-reviewSkill
- seo-audit-reportSkill
- user-researchSkill
- video-contextSkill
The file
We split this CLAUDE.md into the rules it gives an agent
9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
No "done" without an independent verifier (pstack): Before any task is reported done, by a coding agent or by an agency agent, a verifier …
- Very specific: line 58
Add an entry to MODEL_REGISTRY in registry.py.
- Very specific: line 61
Add a routing test in tests/test_model_router.py (rule 23).
- Very specific: line 62
Update docs/architecture/overview.md if the capability profile changes.
- Very specific: line 66
Add the category string to classifier.py.
- Distinctive: line 67
Add its matching logic — keyword, heuristic, or metadata.
- Very specific: line 69
Add tests under "Task classification" in tests/test_model_router.py.
- Very specific: line 89
All router tests are in tests/test_model_router.py:
- Very specific: line 95
Always cover after a change: manual override still wins.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md — router/
Model routing affects every request in the system.
The invariants you must not break are
CLAUDE.mdrules 21–23. Read those first. This file covers how selection works and how to extend it.
Verification rule (mirrored from CLAUDE.md §2, binding on every agent)
<!-- pstack-verification:start -->- No "done" without an independent verifier (pstack). Before any task is reported
done, by a coding agent or by an agency agent, a verifier that did not write the
change tries to break it. It exercises the real artifact (runs the feature, the
tests, the built page; not "it compiles", not the author's own report) and returns
PASS,PASS+NOTES, orFAILwith a report: what it checked, what it found broken, what was fixed, and the evidence (command output; screenshots for any UI change).FAILsends the work back: fix every defect it found, then verify again, until it passes. OnlyPASSorPASS+NOTESpermits a done claim, and the report quotes that verdict. Work in small units that each end in a check. Agency tasks enforce this in code (tasks/verification.py, live controlTASK_VERIFICATION_REQUIRED). Source: pstack'sprinciple-prove-it-worksand its independent per-PR verdict (github.com/cursor/plugins/tree/main/pstack, github.com/michael-denyer/pstack-claude). This rule is mirrored byte-for-byte in every agent instruction file;python scripts/check_verification_rule.pyfails if a copy drifts.
<!-- pstack-verification:end -->What this package does
The central model-selection layer for all API surfaces.
| File | Role |
model_router.py | ModelRouter.route() → RoutingDecision |
classifier.py | classify_task() → task category string |
registry.py | Model capability registry, best_model_for() |
health.py | Ollama /api/tags health check with TTL cache |
Selection priority, highest first:
- Manual override —
X-Model-Overrideheader oroverride_modelkwarg MODEL_MAPenv var, or the built-in Anthropic alias table- Heuristic — task classification into a capability-registry lookup
- Default —
AGENT_EXECUTOR_MODEL
Local Ollama model names are passthrough: they bypass the alias table entirely and
resolve to RoutingDecision(selection_source="passthrough").
The health check is cached with TTL ROUTER_HEALTH_CACHE_TTL (default 60s). The cache is
deliberately invalidated before fallback retries — that is not a bug.
Adding a model
- Add an entry to
MODEL_REGISTRYinregistry.py. - Set
strengthsaccurately — it drives heuristic selection. - Set
cost_tier(1 = cheapest) — it drives fast-response routing. - Add a routing test in
tests/test_model_router.py(rule 23). - Update
docs/architecture/overview.mdif the capability profile changes.
Adding a task category
- Add the category string to
classifier.py. - Add its matching logic — keyword, heuristic, or metadata.
- List the category in
strengthson theMODEL_REGISTRYentries that serve it. - Add tests under "Task classification" in
tests/test_model_router.py.
Environment variables
| Variable | Effect |
MODEL_MAP | Colon-separated alias overrides, e.g. claude-sonnet-4-6:deepseek-r1:32b |
ROUTER_EXTRA_MODELS | Add models at runtime: name:type:strength1+strength2 |
ROUTER_HEALTH_CHECK_ENABLED | false disables health filtering (useful in tests) |
ROUTER_HEALTH_CACHE_TTL | Health cache TTL in seconds (default 60) |
DENIED_MODEL_IDS | Operator deny-list (packages/ai/model_policy.py): route() moves a denied resolved_model to the next allowed fallback and drops denied ids from fallback_chain; if every option is denied the decision is left unchanged so resolved_model stays non-empty (rule 21) and dispatch refuses it |
ROUTER_FAST_RESPONSE_CHARS | Char threshold for fast_response classification (default 200) |
AGENT_EXECUTOR_MODEL | Final fallback when nothing else resolves |
Testing
All router tests are in tests/test_model_router.py:
pytest -x tests/test_model_router.pyAlways cover after a change: manual override still wins; the built-in alias table maps
correctly; heuristic fallback fires when no alias matches; health-check bypass works with
ROUTER_HEALTH_CHECK_ENABLED=false; reset_router() isolates the singleton between
tests.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

