https://github.com/workweave/router
Model router for agentic systems. Routes every prompt to the right model in <50ms. Cut costs 40-70% with just an endpoint change.
https://github.com/workweave/router
agentic-coding ai-gateway anthropic claude-code codex model-router openai-compatible
Last synced: 4 days ago
JSON representation
Model router for agentic systems. Routes every prompt to the right model in <50ms. Cut costs 40-70% with just an endpoint change.
- Host: GitHub
- URL: https://github.com/workweave/router
- Owner: workweave
- License: other
- Created: 2026-04-27T17:56:27.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-07-07T02:19:13.000Z (11 days ago)
- Last Synced: 2026-07-07T04:11:12.794Z (10 days ago)
- Topics: agentic-coding, ai-gateway, anthropic, claude-code, codex, model-router, openai-compatible
- Language: Go
- Homepage: https://weaverouter.com
- Size: 12.5 MB
- Stars: 763
- Watchers: 0
- Forks: 33
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-infra-for-ai - workweave/router - A model router for agentic systems that routes prompts to the most suitable LLM, optimizing performance and cost by dynamically selecting from various providers like Anthropic and OpenAI. (LLMOps / LLM Gateways & Proxies)
- awesome-ccamel - workweave/router - Model router for agentic systems. Routes every prompt to the right model in <50ms. Cut costs 40-70% with just an endpoint change. (Go)
README
**One endpoint. Every model. Always the right one.**
A drop-in proxy for Anthropic, OpenAI, and Gemini that picks the best model
for *every* request: using a tiny on-box embedder, not a vibes-based prompt.
[](https://app.workweave.ai/reports/repository/org_QWsHDcRQWQEs6RpkdEZrlFK8/https%3A%2F%2Fgithub.com/1222789989)
[](go.mod)
[](https://github.com/workweave/router/actions/workflows/test.yml)
[](https://www.elastic.co/licensing/elastic-license)
[](https://github.com/workweave/router/deployments)
*Built by [Weave](https://www.workweave.ai): The #1 engineering intelligence platform,
loved by Robinhood, PostHog, Reducto, and hundreds of others.*
---
## What it does
Point Claude Code, Codex, Cursor, or your own app at `localhost:8080`. The router:
- 🎯 **Routes per request.** A cluster scorer derived from
[Avengers-Pro](https://arxiv.org/abs/2508.12631) [^1] picks the right
model from your enabled providers, every turn.
- 🔌 **Speaks everyone's API.** Anthropic Messages, OpenAI Chat Completions,
Gemini native. Streaming, tools, vision, the works.
- 🧠 **Knows OSS too.** DeepSeek, Kimi, GLM, Qwen, Llama, Mistral via
OpenRouter (or any OpenAI-compatible endpoint).
- 🔒 **BYOK by default.** Provider keys stay on your box, encrypted at rest.
- 📊 **Observable.** OTLP traces out of the box. See them in the Weave dashboard (http://localhost:8080/ui/dashboard) or drop in Honeycomb, Datadog,
Grafana, whatever.
## 30-second quickstart
The fastest way: point Claude Code, Codex, or opencode at the **hosted**
Weave Router with one command. No clone, no Docker, no Postgres.
```bash
npx @workweave/router
```
That's it. The installer asks which tool (Claude Code, Codex, or opencode),
walks you through scope (user vs. project), grabs a router key, and wires
the right config file. Other flavors:
```bash
npx @workweave/router --claude # skip the picker, Claude Code
npx @workweave/router --codex # skip the picker, OpenAI Codex CLI
npx @workweave/router --opencode # skip the picker, opencode
npx @workweave/router --scope project # per-repo, commits settings.json (or .codex/ / opencode.json)
npx @workweave/router --local # self-hosted localhost:8080
npx @workweave/router --base-url https://router.acme.internal
npx @workweave/router@0.1.0 # pin a version
```
Requires Node ≥ 18 (Claude Code and opencode paths also need `jq`). Full
flag reference: [install/npm/README.md](install/npm/README.md).
### Or: self-host the whole stack
If you want the router (and dashboard) running on your own box:
```bash
# 1. Drop a provider key in. OpenRouter is the recommended baseline.
echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env.local
# 2. Boot Postgres + router on :8080 and seed an rk_ key.
make full-setup
```
The router is up at , the dashboard at
(password: `admin`), and your `rk_...` key
prints in the logs.
```bash
# Call it like Anthropic
curl -sS http://localhost:8080/v1/messages \
-H "Authorization: Bearer rk_..." \
-d '{"model":"claude-sonnet-4-5","max_tokens":256,
"messages":[{"role":"user","content":"hi"}]}'
# ...or like OpenAI
curl -sS http://localhost:8080/v1/chat/completions \
-H "Authorization: Bearer rk_..." \
-d '{"model":"gpt-4o-mini",
"messages":[{"role":"user","content":"hi"}]}'
# Peek at the routing decision without proxying
curl -sS http://localhost:8080/v1/route -H "Authorization: Bearer rk_..." -d '...'
```
### Optional: self-host the frozen HMM policy
The default stack uses the in-process cluster scorer. To run the frozen HMM
policy as a companion container, add a Google API key and use the opt-in target:
```bash
echo 'GOOGLE_API_KEY=...' >> .env.local
make up-hmm
```
This does not change the default strategy. See
[`sidecars/hmm/README.md`](sidecars/hmm/README.md) for artifact verification,
embedding compatibility, and explicit HMM selection.
## Wire it into your tools
**Claude Code.** Run `make install-cc` to wire Claude Code at the local
self-hosted router (it's also invoked automatically at the end of
`make full-setup`). For the hosted router, use `npx @workweave/router`
above.
**Codex** (OpenAI CLI). `npx @workweave/router --codex` patches
`~/.codex/config.toml` (or `/.codex/config.toml` with `--scope project`)
with a managed `[model_providers.weave]` block and sets `model_provider = "weave"`.
Codex's existing `OPENAI_API_KEY` flows through to api.openai.com for the
plan-based passthrough; the router key rides in an `X-Weave-Router-Key` HTTP
header. Re-install and `--uninstall --codex` rewrite/remove only the managed
block, leaving the rest of your Codex config untouched.
**opencode.** `npx @workweave/router --opencode` merges a `provider.weave`
entry into `~/.config/opencode/opencode.json` (or `/opencode.json`
with `--scope project`). It uses opencode's bundled `@ai-sdk/anthropic`
provider pointed at the router's `/v1` endpoint — the router speaks the
Anthropic Messages API natively, so opencode works unmodified. The router
key and identity headers ride alongside the provider config; re-install
rewrites only the managed block and `--uninstall --opencode` strips it.
**Cursor** *(early beta, performance may not be the best).* Settings →
Models → *Override OpenAI Base URL* → `http://localhost:8080/v1`, paste
`rk_...` as the API key.
**Switching on/off.** After installing, `npx @workweave/router off --claude`
(or `--codex` / `--opencode`) routes that client straight to its provider
again without discarding the router config; `on` flips it back, and `status`
reports which way it's pointing. Claude Code also gets `/router-off`,
`/router-on`, and `/router-status` slash commands. Cursor toggles via the same
Settings → Models override above. See [install/README.md](install/README.md#switching-on-and-off).
> Two keys, don't mix them up:
> - `sk-or-...` / `sk-ant-...` / `sk-...` = your **upstream** provider key. Lives in `.env.local`.
> - `rk_...` = your **router** key. Clients send this as a Bearer token.
## Endpoints
| Endpoint | Format |
| ------------------------------ | ---------------------------------------- |
| `POST /v1/messages` | Anthropic Messages, routed |
| `POST /v1/chat/completions` | OpenAI Chat Completions, routed |
| `POST /v1beta/models/:action` | Gemini `generateContent`, routed |
| `POST /v1/route` | Returns the decision, no upstream call |
| `GET /v1/models` · `POST /v1/messages/count_tokens` | Anthropic passthrough |
| `GET /health` · `GET /validate` | liveness + key check |
## Deeper docs
- 📐 [**Configuration reference**](docs/CONFIGURATION.md): every env var,
BYOK encryption, OTel knobs, cluster routing.
- [**Policy router harness**](docs/POLICY_ROUTER_HARNESS.md): contract and
rollout checklist for adding an out-of-process policy model.
- 🛠️ [**Contributing**](CONTRIBUTING.md): layering rules, hot-reload dev,
migrations, tests, the whole engineering loop.
- 🏗️ [**Architecture**](AGENTS.md): package layout, import contracts,
recipes for adding endpoints / providers / strategies.
## Star history
---
[^1]: Zhang, Y. et al. *Beyond GPT-5: Making LLMs Cheaper and Better via
Performance–Efficiency Optimized Routing* (Avengers-Pro).
arXiv:2508.12631, 2025.