Clear model choices for coding tasks, with verification and limits built in.
SmartRouter helps a coding agent decide which model is suitable for a task, when to delegate work, and when to stop. It checks whether a model can do the job safely and within the available budget before comparing eligible options.
This repository provides the routing policy, local host tools, and validation fixtures. The application that runs the agent—the host—connects those decisions to actual model calls, permissions, billing, and project state.
Getting started · How it works · Local example · Current limits · Documentation
Current status: the v3.0 routing policy and local tools are available. Live-provider routing remains experimental, with known accounting and recovery gaps. Start with the local checks below; they do not call a model provider.
Different coding tasks need different capabilities. A small edit, a difficult debugging session, and a change involving private data should not be routed using difficulty or price alone.
SmartRouter makes those decisions explicit:
- Check eligibility first. Permissions, tools, verification, and budget must pass before price or convenience can influence the choice.
- Keep ownership clear. Delegated work receives a defined task and acceptance checks, preferably in its own Git worktree and branch.
- Limit recovery. A task gets at most one repair under its original allowance (R01/R02/R03). Repeated failures and exhausted limits produce a recorded stop.
- Make decisions inspectable. Record the route, reasons, verification evidence, and accounting gaps rather than treating a model's confidence as proof.
SmartRouter applies five checks, in order, to each candidate model profile. A profile identifies a model together with the tools, settings, and qualification evidence needed to use it.
| Check | Beginner explanation |
|---|---|
| 1. Permissions and privacy | Is this model allowed to receive the data and perform the requested action? |
| 2. Capabilities | Does the profile have the required tools, tested abilities, and enough context capacity? |
| 3. Verification | Are the acceptance checks defined and available before work begins? |
| 4. Affordability | Does the conservative cost of work and verification fit the remaining money, calls, and time? |
| 5. Economics | Among eligible options, which route is justified after coordination and review costs are included? |
Missing required evidence blocks a candidate. A cheaper model cannot bypass a
failed check. When no candidate is eligible, the result is blocked.
The policy returns one of five routes:
| Route | Meaning |
|---|---|
direct |
Recommend handling the task with an eligible current profile. |
delegate |
Recommend assigning one bounded task to an eligible isolated worker. |
speculative |
Recommend bounded parallel exploration when the host has explicitly enabled it and the policy conditions pass. |
recommend-escalation |
Recommend another eligible profile when direct work is unsuitable. |
blocked |
Stop because a required condition is missing or has failed. |
The canonical skill defines the decision procedure. The host contract defines the objects and responsibilities an integration must implement.
The v3.0 policy runs authorized tasks without routine human checkpoints. Human-in-the-loop (HITL) involvement is opt-in: a human gate is enabled only when the user explicitly requests it for the task or project.
The default is HumanGate: none. The local supervisor stops automatically when a
deadline expires, a limit is exhausted, progress stalls, or a forbidden effect is
reported. It writes a redacted blocked evidence package with no approval menu.
Terminal stops remain in the task's state file across restarts.
For an explicitly requested human checkpoint, the host passes --human-requested.
That enables a needs-human package. A requested pre-dispatch stop also uses
--gate-raised. The host must retain the user's request and its source across
invocations. Human involvement does not waive eligibility or budget checks.
See the autonomous host policy for the lifecycle and optional human gates.
You need Git, Python, and Bash. The GitHub workflow uses Python 3.12.
On Windows, use Git for Windows with Git Bash available on PATH.
The commands below assume python selects the intended interpreter; on systems
where it is named python3, substitute that command.
git clone https://github.com/StepenkoAnatoli/SmartRouter.git
cd SmartRouter
python tools/validate_skills.py --strict
python tests/smart_router_decisions.pyThese validate the skill packaging and deterministic routing fixtures. A passing fixture suite verifies the documented cases; it does not qualify a live model or demonstrate real-provider savings.
In a fresh clone, install the repository's commit hook and run the complete gate:
python tools/install_hooks.py
python tools/run_regression.pyThe installer sets this clone's core.hooksPath to .githooks. Each subsequent
commit runs the gate against the content being committed and refuses on failure.
The gate includes local credential and application-store checks; an untriaged
finding can stop a commit. Keep credentials out of tracked files.
For the extended onboarding proof in a clean checkout, run:
bash tools/setup_machine.shThat script exercises temporary commit/refusal proofs and local preflight checks. It changes the clone's Git configuration, including its local author identity for the proof. Use a fresh clone for this path and set your intended Git author identity before contributing. The checks do not authorize live spending.
This example runs a harmless Python command under the supervisor. It needs no API key and makes no model call. Use a new task ID and state path for a new task:
python tools/host_watchdog.py --task-id readme-demo --state .local/readme-demo/state.json --timeout 10 -- python -c "print('SmartRouter local example completed')"The supervisor records the attempt in .local/readme-demo/state.json. If the
command succeeds, it exits with code 0.
To see an autonomous stop, run this deliberately failing command with no repair allowance. Use a separate task and state path:
python tools/host_watchdog.py --task-id readme-blocked-demo --state .local/readme-blocked-demo/state.json --timeout 10 --allowance 0 -- python -c "import sys; sys.exit(1)"The supervisor exits with code 2 and writes
.local/readme-blocked-demo/state.blocked.json beside the state file. The package
has status: "blocked", human_requested: false, and actions: []. It records
the stop without requesting human approval. Human involvement requires an
explicit request through --human-requested.
Keep the state files as the record of each task. The supervisor refuses further execution from a terminal state. For new work, choose a new task ID and a new state path; do not reset or discard the old counters.
| Exit code | Meaning |
|---|---|
0 |
The supervised command succeeded. The host still owns the task's full acceptance checks. |
1 |
One corrective attempt is granted within the original allowance. The host decides and performs the repair. |
2 |
Terminal stop: blocked by default, or needs-human when explicitly requested. |
3 |
Invalid configuration or unreadable state; execution is refused. |
This tool supervises one command per invocation. A host integration must supply current budget counters and enforce model dispatch, reservations, and descendant process cleanup. The example is a local supervision demonstration.
The repository contains three skills:
| Skill | Purpose |
|---|---|
| smart-router | Make the routing recommendation for a task or dispatch decision. |
| smart-router-review | Review a result against its acceptance contract and provenance. |
| smart-router-eval-prep | Prepare an evaluation protocol before separately authorized model trials. |
To integrate them, configure your host to read the canonical skill and provide its required inputs: authorized data and actions, exact model profiles, fresh qualification evidence, acceptance checks, price bounds, and remaining allowances. The host then executes eligible decisions and records outcomes.
Cloning this repository does not install the skills into an agent or switch its running model. Provider setup and dispatch adapters belong to the host integration. The worktree guide explains isolated delegation; the lifecycle example shows how the pieces fit together.
The project has a validated policy, deterministic fixtures, local lifecycle tools, and a completed local pilot report. Live-provider comparisons and consumer adoption require their own evidence. The current policy version is v3.0; older release tags describe the snapshots published at those tags.
The live dispatcher now uses a persistent pilot authority to reserve work and mandatory verification before sending. Task and pilot totals survive restarts, and concurrent instances share the same allowance. Failed sends retain their attempts and unknown-usage reservations; complete receipts settle known cost. Verification cash and model-call slots remain protected until the host completes the required checks. See dispatch accounting and recovery.
Input counting still uses the provider's estimate plus a 5% margin. A send can exceed that estimate; its known cost is recorded and further dispatch stops. Older ledgers without a reservation authority require reconciliation. These changes have synthetic process and crash coverage, not live-provider qualification. Corrupt persisted task state now blocks dispatch and preserves the original file. Recovery still needs an authoritative reconciliation process. Shared-resource plans can be required when creating and launching a worker; these checks track declared ports within one registry and do not reserve operating-system resources or coordinate simultaneous registry writers. See the integration notes for the optional worker checks and the exact scope of these fixes.
The October 13 review preserves the original findings. Process-tree cleanup, host qualification, final billing accuracy and integration evidence still limit live-provider operation.
Observed GPT usage is stored in a metadata snapshot. It is cumulative session telemetry, not a final bill or proof of savings. Cached input is included in input totals; reasoning output is included in output totals. Unknown dollar cost remains unknown.
The usage telemetry guide shows how to export these metadata fields, try a synthetic example, and interpret missing counters.
A three-model policy pilot records Luna, GPT-6.1 Sol and Astra on twelve identical synthetic decisions. All matched the expected decision fields; the report also records a reservation-binding ambiguity, coverage gaps and unavailable per-model telemetry. This small run does not establish a production model ranking.
A repeated 24-case stress comparison adds two runs per model, explicit reservation arithmetic, proposal checks, and code traces. It records calculation errors, schema fixes, and remaining runtime gaps with replayable evidence. Usage and billed cost remain unknown.
| Start here when you want to… | Read |
|---|---|
| Understand the exact routing rules | Canonical skill and eligibility gates |
| Build a host integration | Host contract and schemas |
| Reserve dispatch budget and recover uncertain usage | Dispatch accounting and recovery |
| Understand autonomous stops and optional HITL | Host policy |
| Inspect observed use, bugs, and GPT usage | Engineering review |
| Export and interpret token counters | Usage telemetry guide |
| Check reservation arithmetic in model answers | Reservation comparison fixtures |
| Review the local pilot and its limits | Pilot report |
| Trace milestones and historical releases | Project completion record |
| Handle credential rotation and custody checks | Credential runbook |
| Read the original roadmap and source survey | Development plan and routing survey |
New contributors are welcome. Start with the contribution guide and browse good first issues for small, clearly scoped tasks. The guide explains setup, labels, commit messages, bug reports, and pull requests.
Interested in comparing models? Pick a LLM testing issue for GPT repeats, Claude, Gemini preparation, local models, or usage capture. Join the discussion or read the community guide to share results and help others get started.
Work on a feature branch, define acceptance checks before implementation, and run
the local gate before pushing. Open a pull request against main; GitHub runs the
regression gate and watcher proof. Merge only after the required checks pass
against the current base. Keep project-specific consumer code and credential
inventories in their own repositories.
See LICENSE for the license grant and its stated scope.
If you find this project helpful, please consider giving it a ⭐!
You can also help by reporting reproducible bugs, improving the documentation, or contributing a focused fix. Thank you for helping make SmartRouter clearer and more reliable.