higress-group/HiRoute

简体中文

Route agents by task. Route models by stage.
A local-first routing and coordination engine for long-horizon agent tasks.

Website · Download · Documentation · Decision models · 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.

Decision-based routes choose again on each new user turn. Tool continuations in the same turn keep the frozen decision, helping the model reuse its growing context prefix. A context rebuild can require a new decision when HiRoute can no longer recognize the continuation or reuse its previous decision. Choosing again can also keep the same model; cache reuse depends on the provider.

• Latest stable release — macOS Desktop and Linux headless packages for x86_64 and ARM64. Release notes · Download
• 2026-10-14 — Switching Models Loses Cache, Not the Savings. Website article
• 2026-10-04 — GPT-6 Astra × Qwen-3.8 Flash: same quality at 90% lower cost. Website article · Experiments
• HiRoute Is Open Source: Help Your Agents Do More and Your Subscriptions Go Further. Website article
• All news

HiRoute currently provides four routing modes: fixed model, smart saving, custom branches, and free first. Each mode uses the plan's ordered candidates for bounded failover. It also provides agent work plans and Worker delegation; local session, usage, cost, and competence views; and a custom extension API for connecting your own decision service.

Download the current DMG from hiroute.ai, drag HiRoute into Applications, and follow the self-signed package instructions if macOS asks for manual approval. HiRoute supports macOS 15 or later on Apple silicon (arm64) and Intel (x86_64).

Install the current-user CLI and daemon on Linux x86_64 or ARM64 (aarch64) without sudo:

curl -fsSL https://hiroute.ai/install.sh | sh
hiroute service start --output json
hiroute system status --output json

The 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.

1. Connect a supported subscription, registered API, or compatible custom API.
2. For model-based judgment, open Models → Decision models and connect Bailian, OpenRouter Jev, TypeSafe, or a compatible endpoint. Built-in connections need no self-hosted Jev service.
3. Create and publish a routing plan, using smart saving or custom task branches when needed.
4. Connect an Agent client, or expose a Worker plan for delegated tasks.
5. Inspect sessions and model performance to understand the task category, actual model group, and execution result.

Continue with model routing, task routing, or the headless CLI guide.

Review model performance within a task, alongside execution records and user feedback, to inform the next model choice and task delegation. Each score stays linked to its execution stage.

Built-in decision models judge the task category when needed and return simple/complex probabilities for routes with two model groups. They can also assess the previous execution stage. HiRoute supplies the published conditions and scoring criteria, applies your thresholds, and chooses the model group and ordered candidates. Configure these connections in Models → Decision models; you do not need to deploy an extension.

Smart saving has one task scope with economy and primary model groups. Economy is selected when this turn's simple-task probability meets your threshold and no applicable, complete assessment falls below the competence floor. Otherwise HiRoute selects primary. Missing or partial scores stay unrated. An old low score does not lock future turns to primary, and a new turn does not automatically return to economy: HiRoute judges the current work again.

Custom branches separate task categories such as drafting and review. HiRoute first uses the category choice, then the simple/complex degree within that category to choose its regular or optional primary group. A category with only a regular group needs no degree judgment. An assessment belongs to the stage that actually ran; a low drafting score does not upgrade the review category. Only a complete, applicable assessment for the same category, published revision, and frozen criteria can affect this turn's group choice.

Tool continuations keep the decision when HiRoute can recognize the same turn and reuse its frozen decision. Candidate failures use bounded failover: regular candidates may relay to the same category's primary group, while a primary selection stays within primary. Exhaustion fails explicitly. Failover does not create a competence score or change the task category.

The principle is:

Competence blocks risky cost-cutting; complexity creates opportunities to save.

Smart saving also supports heuristic rules. A custom extension is optional: use it when you want to own the model integration, judgment, scoring, and context trimming. The official Jev extension is one implementation of that boundary. Start with decision models and the routing mechanism, the custom extension 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-features

For frontend work, run the checks in the affected application:

cd apps/desktop   # or apps/website
npm ci --ignore-scripts
npm test
npm run build

See 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.

The code map connects user capabilities to architecture, production owners and representative tests.

The latest stable release provides macOS Desktop and Linux headless packages for both x86_64 and ARM64. Download the latest version and read the release notes 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.

Links: LINUX DO — a Chinese-language tech community.