Route agents by task. Route models by stage.
A local-first routing and coordination engine for long-running agent work.
Website · Download · Documentation · Decision API · Contributing
HiRoute is a local control and execution layer for long-horizon agents. It brings model sources, reusable routing plans, agent connections, bounded failover, and execution evidence into one system, available through a Desktop application or a headless CLI and daemon.
It is not a proxy that swaps models on every tool call. HiRoute keeps a selected branch stable through an execution stage, then chooses again at a natural boundary—such as new user input or the context rebuild that follows compaction. This preserves reusable prefixes within a stage and makes model switching friendly to provider KV caches.
| Route long tasks by stage | Use the model that fits the work ahead instead of committing an entire task to one model. |
| Protect quality while saving | Use observed competence to block risky downgrades, while task complexity creates opportunities to use economical models. |
| Keep handoffs bounded | Enforce capability requirements, ordered candidates, and explicit exhaustion instead of silently changing behavior. |
| Learn from execution | Retain the selected branch, actual model, tool outcomes, accepted output, and optional stage competence for later decisions. |
HiRoute currently provides fixed-model, smart-saving, free-first, and ordered-fallback routing; agent work plans and Worker delegation; local session, usage, cost, and competence views; and a public Decision API for custom selection strategies.
Download the current DMG from hiroute.ai, drag HiRoute into Applications, and follow the self-signed package instructions if macOS asks for manual approval. The download page is the authority for validated operating systems and architectures.
Install the current-user CLI and daemon without sudo:
curl -fsSL https://hiroute.ai/install.sh | sh
hiroute service start --output json
hiroute system status --output jsonThe installer verifies the published package manifest and checksums and does not start a service automatically. See the Linux installation guide and CLI reference for service lifecycle and machine-readable commands.
- Connect a supported subscription, registered API, or compatible custom API.
- Create and publish a routing plan for the task and cost profile you want.
- Connect an Agent client, or expose a Worker plan for delegated tasks.
- Inspect sessions and runtime performance to understand the selected branch and actual model.
Continue with model routing, task routing, or the headless CLI guide.
The performance view follows the models selected by the active routing-plan revision; users do not need to enter internal model IDs. The screenshot uses realistic synthetic data rendered by real product components. It demonstrates the UI states and is not a model benchmark.
A routing execution round begins with one branch decision. Ordinary tool continuations keep that decision while the current context remains reusable. HiRoute decides again when a new user request changes the work, or when a long session compacts and rebuilds its context. The routing engine determines whether a decision can be inherited; clients do not need to emit a separate compaction event. A provider or model failure can still use the plan's bounded fallback inside the round; fallback is distinct from a new classification decision.
At a decision boundary, a service may do two related jobs in one response:
- choose one of the branch IDs allowed by HiRoute for the next round;
- optionally assess how competently the previous model handled its execution stage.
The official TypeSafe Jev extension implements this contract with one OpenRouter request. Its Rules policy uses task complexity and the optional assessment together: choose economy only when the simple-task probability meets the threshold and no valid current score falls below the competence floor. Otherwise, choose primary. A missing score leaves the decision to complexity alone.
The principle is:
Competence blocks risky cost-cutting; complexity creates opportunities to save.
Jev is optional. You can use built-in rules or implement the same general multi-branch contract with an LLM or your own policy. Start with the decision mechanism, the API guide, or the canonical OpenAPI document.
HiRoute is a Rust workspace with a Tauri Desktop client and an Astro website. The Rust toolchain
is pinned in rust-toolchain.toml; Desktop uses Node.js 24 and the website uses Node.js 22.
git clone https://github.com/higress-group/HiRoute.git
cd HiRoute
cargo fmt --check
cargo test --locked --workspace --exclude hiroute-desktop --all-featuresFor frontend work, run the checks in the affected application:
cd apps/desktop # or apps/website
npm ci --ignore-scripts
npm test
npm run buildSee CONTRIBUTING.md for native dependencies, Clippy, validation scope, and language conventions. Native Desktop behavior and real-provider integration require their respective environments; a source build alone is not product acceptance.
| Path | Responsibility |
|---|---|
apps/desktop |
Desktop UI and Tauri host |
crates/cli, crates/daemon |
Headless client and local role-all service |
crates/application, crates/client-core |
Application workflows and shared client behavior |
crates/gateway, crates/gateway-core |
Agent-facing protocols, routing, execution, and fallback |
crates/observation, crates/local-storage |
Local execution evidence, queries, and persistence |
decision-extensions |
Decision mechanism, OpenAPI contract, screenshots, and official Jev service |
contracts, assets |
Current runtime contracts, model metadata, and product resources |
apps/website |
Bilingual hiroute.ai site, downloads, and release publication |
e2e, tools, scripts |
Product scenarios, validation tools, packaging, and automation |
HiRoute is an MVP. Platform and architecture claims are tied to the evidence for each release; source availability does not imply that every environment has been validated. Current Agent integrations and planned directions remain separate on the website.
HiRoute is licensed under the Apache License 2.0. Use GitHub Issues for bugs and feature requests. Report security issues and crash reports through the process in SECURITY.md.
