Development
Plugin
bitrouter
The self-improving LLM router that optimizes your agentic workflows with every run, works with any harnesses, any models, any loops. You're tokenmaxxing in production.
Plugin Signal71/100Solid
maintained100
capable29
documented100
adopted50
Install on Claude Code
> /plugin marketplace add bitrouter/bitrouter> /plugin install bitrouter@bitrouter
What's inside
Skills
3/bitrouterUse this skill when the user wants to install, configure, run, or troubleshoot BitRouter — an LLM proxy that runs two ways: a local Rust daemon at http://localhost:4356 (BYOK) or BitRouter Cloud at https://api.bitrouter.ai/v1 (managed, brk_* keys, Stripe credits or x402 wallet)./evaluating-bitrouter-routesUse when evaluating BitRouter route decisions or Eval Exchange subjects with task-native verifiers, human reviewers, private enterprise evaluators, agentic judges, or genuinely uncategorized evaluator sources./run-bitrouter-benchmarkUse when planning, launching, resuming, auditing, or reproducing a BitRouter Terminal-Bench 2.1 benchmark with Harbor, Terminus 2, and AWS EC2, including short policy iterations, one-time controls, model comparisons, or public full runs.
Badges
9
README
1BitRouter
The self-improving LLM router that optimizes your agentic workflows with every run, works with any harnesses, any models, any loops.
You're tokenmaxxing in production. Every step of every loop bills at frontier prices — file reads, tool calls, sub-agent hops, retries. Most don't need it. BitRouter routes each call, tool, and agent to the cheapest path that still reaches the goal, and tightens that routing as the loop runs.
Cost is live today — latency and accuracy are next.
Three primitives, one gateway
An agentic loop consumes three things. Other routers govern only the first. BitRouter makes all three routable, observable, and governed:
- Models — route LLM calls across providers, accounts, and wire protocols: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Google Gemini. (the classic router, cross-protocol — any request format to any upstream, and back)
- Capabilities — an MCP gateway and an AgentSkills gateway: tools and skills become governed, routable resources instead of hardcoded endpoints. (The skills gateway folds into the MCP gateway once the MCP skills extension reaches production.)
- Agents — an ACP gateway: sub-agents become first-class routable primitives, so a task can go to the sub-agent that best fits the loop's objective — just as a call routes to the best-fit model. (Local sub-agents over stdio today; remote gateways arrive with ACP v2.)
Optimizing a loop isn't just model selection — it's choosing the model, the tool, and the sub-agent that best serve the loop's objective at every step that gets it to its goal.
The self-improving loop
BitRouter wraps your agentic loop in a second loop. bitrouter.yaml declares
providers, presets, and whether the process may publish; policy-lock.yaml is
the only live route authority. The routing key is context-aware and lives as
code: it is the step in the loop, not just the model name.
policy:
path: ./policy-lock.yaml
mode: adaptive # authorizes explicit publication only
presets:
auto:
model: openai-codex:gpt-5.6-sol
policy: auto
The v2 lock behind @auto contains the tier models, canonical agent_trace
routes, capability guardrails, and a decision certificate for every explicit
route. @auto:cost selects the cost variant when one is defined; explicit
physical model IDs remain passthrough.
Against that spec BitRouter provides the control plane for an act → observe → evaluate → compile cycle:
- Act — the router reads the lock and rewrites each
@preset[:variant]call to its tier's model: policy routing, cross-protocol translation, multi-account failover. - Observe — telemetry attributes every hop with cost, tokens, latency, and outcome, exported to Prometheus or any OTLP backend.
- Evaluate — the generic eval exchange lets task-native tests, humans, enterprise systems, or an external agentic judge submit the same versioned outcome contract. BitRouter admits, disputes, and snapshots evidence; it does not pretend one bundled judge is universal.
- Compile — the policy compiler turns a frozen admitted-evidence snapshot into a deterministic, certificate-backed
policy-lock.yamlcandidate (an npm-style manifest/lock split, git-owned). Review and publication are explicit; the evidence database never changes a live route.
You choose what the external evaluator measures — cost, latency, quality, or a private objective — while the active lock remains the only authority for live policy routing.
Benchmarks
Today cost is the validated objective: on Terminal-Bench 2.1, gpt-5.5 with BitRouter cut cost 32.8% at near-parity accuracy (−1.1 pp), by offloading routine steps to a cheaper model. Latency and accuracy objectives — and more base models — are landing next.
| Base model | Cost vs baseline | Latency vs baseline | Accuracy vs baseline |
|---|---|---|---|
gpt-5.5 | **−32.8%**¹ | coming soon | coming soon |
gpt-5.6 | coming soon | coming soon | coming soon |
claude-opus-4.8 | coming soon | coming soon | coming soon |
claude-sonnet-5 | coming soon | coming soon | coming soon |
claude-fable-5 | coming soon | coming soon | coming soon |
¹ Cost-optimization run on Terminal-Bench 2.1: −32.8% zero-cache imputed cost (audited range 28.6–32.8% by cache share) at near-parity accuracy, −1.1 pp (76.1% vs 77.3%, within single-attempt noise).
This is a mechanism study under a modified protocol, not a Terminal-Bench leaderboard submission — read the experiment limitations before citing the numbers. Full reports live in benchmarks/; complete traces, tool calls, usage, policy decisions, configs, and checksums are in the BitRouterAI/benchmarks dataset.
Comparison
Every gateway below routes model calls. BitRouter is the only one that also makes tools and agents routable, and optimizes the whole loop rather than a single call.
| BitRouter | OpenRouter | LiteLLM | TensorZero | Portkey | Bifrost | |
|---|---|---|---|---|---|---|
| Routable primitives | Models + tools + agents (MCP + ACP) | Models | Models + tools (MCP) | Models | Models + tools (MCP) | Models + tools (MCP) |
| Routing key | The loop step (last tool called) | Model name | Model + request tags | Model name | Model + metadata | Model name |
| Optimizes | The loop, multi-objective (cost today) | Static routing | Static routing | The model | Static routing | Static routing |
All but OpenRouter are open-source and self-hostable; BitRouter and TensorZero are Rust.
What BitRouter is not
- Not a static gateway — it observes routed agent loops and compiles admitted external outcomes into a git-owned
policy-lock.yamlyou can read, diff, and revert. The live route never changes implicitly between publications. - Not an orchestration framework — it doesn't define your agent's control flow, steps, or state; it routes the calls, tools, and sub-agents your loop already makes.
- Not an agent harness — it runs under Claude Code, Codex, and the rest, not instead of them.
Install
# macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bitrouter/bitrouter/releases/latest/download/bitrouter-installer.sh | sh
# Homebrew
brew install bitrouter/tap/bitrouter
# npm
npm install -g bitrouter
cargo install bitrouter
Quick Start
BitRouter is a local proxy between your agent and every LLM provider. One env-var swap — no harness changes required:
- OPENAI_BASE_URL=https://api.openai.com/v1 # hardwired to one provider, no fallback
+ OPENAI_BASE_URL=http://localhost:4356/v1 # all providers, automatic failover
CLI
BitRouter runs as a local daemon — start it with your own keys or a Cloud sign-in.
Bring your own keys (BYOK) — auto-detected from the environment, no config file needed:
export OPENAI_API_KEY=sk-... # ANTHROPIC_API_KEY / GEMINI_API_KEY also work
bitrouter start # proxy running at http://localhost:4356
Or sign in to BitRouter Cloud — use browser OAuth interactively or store an existing API key in CI:
bitrouter cloud login # RFC 8628 device flow against api.bitrouter.ai
bitrouter cloud login --api-key "$BITROUTER_API_KEY" # non-interactive CI login
bitrouter start # `bitrouter` provider auto-enables once signed in
The same credential also drives a gh api-style raw client—no daemon required:
bitrouter cloud api /v1/models
bitrouter cloud api /v1/chat/completions --input request.json
Point your agent runtime at http://localhost:4356 and any available provider is live. For advanced routing rules, guardrails, or multi-account failover, scaffold a config with bitrouter init (writes ./bitrouter.yaml).
bitrouter start / stop / restart # daemon lifecycle
bitrouter route <model> # trace how a model name resolves
bitrouter key sign --user <id> # mint a scoped brvk_ API key
bitrouter cloud keys / usage / billing # manage your cloud account
bitrouter cloud api /v1/models # call Cloud APIs directly
See docs/CLI.md for the full command reference, flags, and config resolution.
Agent Skill
BitRouter ships an Agent Skill — /bitrouter — so AI
coding agents can install, configure, migrate to, and troubleshoot BitRouter on
their own. It lives in this repo at skills/bitrouter/, kept in sync
with the code.
npx skills add bitrouter/bitrouter # via the generic skills CLI
# ...or add this repo as a plugin marketplace in Claude Code / Codex
MCP
Use BitRouter from any MCP client — it exposes complete, list_models, and status as MCP tools (the origin server, distinct from the MCP gateway that proxies your own MCP servers):
bitrouter mcp serve # stdio → local daemon at 127.0.0.1:4356
bitrouter mcp install --client claude # print the Claude/Cursor mcpServers config block
Add --transport http to target the multi-tenant cloud backend.
API
BitRouter exposes an OpenAI- and Anthropic-compatible HTTP API on http://localhost:4356, so any SDK or client works unchanged. The full endpoint reference and OpenAPI spec live in bitrouter/bitrouter-docs (rendered at bitrouter.ai).
Workflow templates
Ready-made policy specs for common agentic workflows — a starting point that routes well out of the box, before you tune it for your own loop. Coming soon in templates/.
Models & providers
BitRouter routes to a model, not a provider. Each family below is served by many providers — its own lab, hyperscalers (AWS Bedrock, Alibaba Cloud), gateways (OpenRouter, OpenCode), and serverless clouds — and BitRouter picks the cheapest route per call. Bring your own key to any of them, or use one BitRouter Cloud account with no keys at all.
| Lab | Latest models |
|---|---|
| DeepSeek | DeepSeek V4 Pro / Flash |
| Alibaba | Qwen3.7 Max / Plus |
| Moonshot | Kimi K2.7 Code / K2.6 |
| Z.ai | GLM-5.2 / 5.1 |
| MiniMax | MiniMax M3 / M2.7 |
| Xiaomi | MiMo V2.5 Pro / V2.5 |
| StepFun | Step 3.7 Flash / 3.5 Flash |
Plus every frontier model from OpenAI, Anthropic, Google, and xAI — over your own keys, a subscription sign-in (Claude Pro/Max, GitHub Copilot, ChatGPT Codex), or BitRouter Cloud. Full catalog in the registry/.
Harness integrations
Any agent runtime that speaks OpenAI or Anthropic APIs works with BitRouter out of the box — set OPENAI_BASE_URL=http://localhost:4356/v1 and you're done. The following harnesses are tested and supported:
| Harness | Status | Notes |
|---|---|---|
| Claude Code | ✅ | LLM gateway guide |
| OpenAI Codex | ✅ | bitrouter launch --agent codex or custom model providers |
| OpenCode | ✅ | Via models.dev |
| Hermes Agent | ✅ | Native plugin — hermes-bitrouter-plugin |
| OpenClaw | ✅ | Native plugin — bitrouter-openclaw |
| Pi-Agent | ✅ | Model configuration guide |
The full provider and harness catalog lives in github.com/bitrouter/bitrouter/registry.
Features
Beyond the gateways above, the production controls for running agents unattended:
- Multi-account failover + load-balancing — reroute mid-run; a rate-limit at file 140 never re-pays for files 1–139
- Virtual keys (
brvk_) scoped per agent or user — no agent holds an upstream key - Per-agent spend caps + loop guards to contain runaway cost
- Injection + output guardrails at the router, before requests leave your network
- Zero-config auto-detection + custom OpenAI-/Anthropic-compatible providers
Talk to founders
Try BitRouter Cloud → or reach out directly:
Want a first-party provider integration, or building an open-source agent/harness? Email kelsenliu@bitrouter.ai or book a meeting — open-source builders get up to 50% off for you and your community.
Development
docs/DEVELOPMENT.md— workspace architecture and SDK internalsCONTRIBUTING.md— contribution workflow, issue reporting, and provider updatesCLAUDE.md— guidance for AI coding agents working in this repositoryskills/— the/bitrouterAgent Skill (source of truth)
Star History
License
Licensed under the Apache License 2.0.
File tree
547bitrouter/bitrouterView on GitHub
.agents/
plugins/
marketplace.json
.claude-plugin/
marketplace.json
plugin.json
.codex-plugin/
mcp.json
plugin.json
.gitattributes
.github/
copilot-instructions.md
ISSUE_TEMPLATE/
bug_report.yml
config.yml
feature_request.yml
workflows/
ci.yml
notify-release.yml
package.yml
pr.yml
registry-sync.yml
release-plz.yml
release.yml
.gitignore
AGENTS.md
apps/
bitrouter/
Cargo.toml
src/
acp_cli.rs
adequacy/
mod.rs
reliability.rs
report.rs
store.rs
agent_registry.rs
agents.rs
assemble.rs
auth/
db.rs
entities/
api_keys.rs
mod.rs
users.rs
events.rs
hook.rs
keys.rs
mod.rs
tests.rs
claude_code.rs
cloud/
api.rs
cli.rs
mod.rs
commands.rs
continuation.rs
daemon.rs
db/
migration/
m20240101_000001_create_auth_tables.rs
m20240101_000002_create_metering_tables.rs
m20240101_000003_rename_legacy_charge_column.rs
m20240101_000004_create_adequacy_table.rs
m20240101_000005_create_adequacy_exploration_table.rs
m20240101_000006_create_adequacy_semantic_success_table.rs
m20240101_000007_add_metering_evidence.rs
m20240101_000008_add_metering_reconciliation.rs
m20240101_000009_create_adequacy_reliability_events.rs
m20240101_000010_create_eval_exchange.rs
m20240101_000011_scope_eval_exchange.rs
m20240101_000012_create_trajectory_ledger.rs
m20240101_000013_create_continuation_registry.rs
mod.rs
mod.rs
error_report.rs
eval/
admission.rs
api.rs
compiler.rs
mod.rs
settlement.rs
store.rs
types.rs
fleet_mcp.rs
fleet.rs
gateways.rs
harness.rs
lib.rs
main.rs
mcp_registry.rs
metering/
db.rs
entities/
mod.rs
requests.rs
mod.rs
pricing.rs
reader.rs
reconciliation.rs
recorder.rs
store.rs
tests.rs
onboarding.rs
optimization/
discovery.rs
evaluator.rs
mod.rs
orchestrator.rs
runner.rs
setup.rs
output/
error.rs
human.rs
mod.rs
reports/
admin.rs
agents.rs
config.rs
daemon.rs
eval.rs
mcp.rs
mod.rs
observe.rs
optimization.rs
policy.rs
routing.rs
skills.rs
tools.rs
trajectory.rs
update.rs
paths.rs
policy/
policy_compile.rs
policy_lock.rs
policy_table_router.rs
hook.rs
mod.rs
policy.rs
store.rs
tests.rs
reload.rs
result_contract.rs
risk.rs
routing_preview.rs
skills/
skills_catalog.rs
skills_query.rs
cli.rs
format.rs
mod.rs
root.rs
spawn.rs
style.rs
tools.rs
trajectory/
canonical.rs
correlation.rs
evaluation.rs
guard.rs
health.rs
mod.rs
publisher.rs
replay.rs
settlement.rs
store.rs
types.rs
tui/
event.rs
highlight.rs
mod.rs
notify.rs
pty.rs
pump.rs
state/
diff.rs
events.rs
keys.rs
layout.rs
mod.rs
overlay.rs
pane.rs
tests.rs
term.rs
ui.rs
update.rs
workflow_state/
archive.rs
counterfactual.rs
decision.rs
extractors/
extractors.rs
claude_code.rs
codex.rs
generic.rs
hermes.rs
openclaw.rs
smithers.rs
terminus_2.rs
fixture.rs
ir.rs
mod.rs
online.rs
real_trace.rs
replay.rs
reward_feedback.rs
reward.rs
session.rs
shadow_policy.rs
tests/
acp.rs
agent_trace_generalization.rs
cloud_api.rs
daemon.rs
e2e.rs
eval_exchange_equivalence.rs
fixtures/
trajectory/
complete_chat.jsonl
complete_messages.jsonl
complete_responses.jsonl
recovery_then_repeat.jsonl
workflow_state/
workflow_state_bundle_smoke.sh
claude_code/
edit_tool.json
opening.json
test_tool.json
tool_followup.json
codex/
previous_response.json
hermes/
midstream_planning.json
opening.json
real_session_opening_20260703.json
tool_followup.json
openclaw/
runtime_stub.json
full_stack.rs
observe_hierarchy.rs
onboarding.rs
optimization_discovery.rs
optimization_output.rs
policy_eval_control_plane.rs
smithers_reward_loop.rs
terminus_2_workflow_state.rs
trajectory_progress_control.rs
workflow_state_real_agent_e2e.rs
workflow_state_replay.rs
benchmarks/
001-2026-07-10-tbench-v2.1-codex-gpt55-kimi-k27.md
README.md
Cargo.lock
Cargo.toml
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
crates/
bitrouter-cloud-sdk/
Cargo.toml
src/
api.rs
auth/
commands.rs
credentials.rs
flow.rs
metadata.rs
mod.rs
settings.rs
lib.rs
management/
billing.rs
budgets.rs
byok.rs
error.rs
keys.rs
mod.rs
namespaces.rs
oauth_clients.rs
policies.rs
presets.rs
tests.rs
types.rs
usage.rs
provider/
applier.rs
mod.rs
settlement.rs
tests/
oauth_device_flow.rs
bitrouter-guardrails/
Cargo.toml
src/
config.rs
hooks.rs
lib.rs
plugin.rs
rules.rs
tests.rs
bitrouter-mcp/
Cargo.toml
examples/
mcp-stdio-local.rs
README.md
src/
backend/
cloud.rs
local.rs
mod.rs
capabilities/
cost.rs
escalation.rs
fleet.rs
human.rs
mod.rs
routing.rs
skill_catalog.rs
skills.rs
error.rs
install.rs
lib.rs
server.rs
tests/
gateway_roundtrip.rs
install_write.rs
multitenant_http.rs
stdio_smoke.rs
bitrouter-observe/
benches/
observe_overhead.rs
Cargo.toml
src/
acp.rs
lib.rs
otel/
auth_client.rs
bearer.rs
cardinality.rs
config.rs
exporter.rs
http_layer.rs
metrics.rs
mod.rs
processor_runtime.rs
span_attributes.rs
transport.rs
bitrouter-providers/
Cargo.toml
providers/
bitrouter.toml
src/
anthropic/
headers.rs
mod.rs
antigravity/
agy_client.rs
mod.rs
protocol.rs
apply.rs
builtin.rs
claude_code.rs
codex/
headers.rs
jwt.rs
mod.rs
copilot/
exchange.rs
headers.rs
mod.rs
entry.rs
import/
antigravity.rs
claude_code.rs
codex.rs
grok.rs
keychain.rs
mod.rs
lib.rs
oauth/
auth_code.rs
credential_store.rs
device_code.rs
listener.rs
login.rs
mod.rs
pkce.rs
refresh.rs
registry.rs
registry/
apply.rs
cache.rs
fetch.rs
mod.rs
types.rs
supergrok/
mod.rs
bitrouter-sdk/
Cargo.toml
src/
acp/
... 249 moreFAQ
bitrouter is a Claude Code plugin with 3 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes bitrouter, evaluating-bitrouter-routes, run-bitrouter-benchmark. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is bitrouter?
- The self-improving LLM router that optimizes your agentic workflows with every run, works with any harnesses, any models, any loops. You're tokenmaxxing in production.
- How do I install bitrouter?
- Run these in Claude Code: /plugin marketplace add bitrouter/bitrouter then /plugin install bitrouter@bitrouter. Then prompt normally.
- Does bitrouter auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is bitrouter free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.