claude-code-router

README

claude-code-router

Local HTTP router for Claude Code. Forwards /v1/* requests to one of several LLM providers (Anthropic subscription, MiniMax, local Ollama, …) based on the request's model field, using a declarative YAML config. Switch backends mid-session with /model <name> — no router or session restart.

Install

1. Install the binary onto your PATH:

   make install
   

   Drops claude-code-router into $(go env GOPATH)/bin/.

2. Create the config at ~/.config/claude-code-router/config.yaml (XDG; falls back to the legacy ~/.claude-code-router/config.yaml if that's the only one present):

   mkdir -p ~/.config/claude-code-router
   cp docs/config.example.yaml ~/.config/claude-code-router/config.yaml
   chmod 600 ~/.config/claude-code-router/config.yaml
   # then edit the file, paste real provider tokens
   

   The example config in full:

   router:
     default_provider: anthropic-subscription
   
   providers:
     anthropic-subscription:
       upstream: https://api.anthropic.com
       # no token: → router forwards client's Authorization header
       #   (Claude Code's subscription OAuth bearer passes through untouched)
       models:
         - "claude-opus-*"
         - "claude-sonnet-*"
         - "claude-haiku-*"
         - "opus"
         - "sonnet"
         - "haiku"
   
     minimax:
       upstream: https://api.minimax.io/anthropic
       token: "<YOUR_MINIMAX_API_KEY>"
       models:
         - "MiniMax-*"
   
     ollama-local:
       upstream: http://localhost:11434
       token: "ollama"
       models:
         - "qwen*"
   
   # Short names that resolve to full model identifiers before routing.
   # Upstream always sees the resolved full name. Single-hop, case-sensitive.
   aliases:
     qwen: qwen3.6:35b-a3b-coding-nvfp4
     minimax: MiniMax-M3-highspeed
     opus: claude-opus-4-7
   

   Full schema reference: docs/config.md. Add more providers (or remove the ones you don't use) by following the same block shape.

   Config edits are hot-reloadable — after editing config.yaml, send SIGHUP to the running router to pick up the change without a process restart (in-flight requests are preserved):

   kill -HUP $(pgrep claude-code-router)
   # log shows: config reloaded old_providers=N new_providers=M
   

   A malformed config is rejected and the old config stays active. See docs/config.md for the full reload + failure behavior. A full restart (launchctl kickstart -k / systemctl --user restart) is only needed for binary upgrades or --listen address changes.

3. Run it continuously in the background — pick your platform:

   • macOS: docs/launchd-service.md
   • Linux: docs/systemd-user-service.md

4. Add the clauder shell function (below) so your Claude Code sessions can route through it.

clauder shell function

clauder is a one-line wrapper that points Claude Code at the local router for a single invocation. The choice stays per-session: claude still talks directly to Anthropic, clauder goes through the router.

Append to ~/.zshrc (or ~/.bashrc on Linux):

# Routes Claude Code through claude-code-router on 127.0.0.1:8788.
# IMPORTANT: do NOT set ANTHROPIC_API_KEY — that overrides the subscription
# OAuth bearer and breaks auth. clauder sets only ANTHROPIC_BASE_URL.
clauder() {
  ANTHROPIC_BASE_URL="http://127.0.0.1:8788" claude "$@"
}

Reload the shell (source ~/.zshrc) and use clauder whenever you want the router in the loop:

clauder                 # interactive Claude Code session via the router
clauder --resume        # resume previous session via the router
clauder -p "summarize"  # one-shot prompt via the router
claude                  # direct to Anthropic, router not involved

Switching providers mid-session

The router decides per-request. Inside any clauder Claude Code session:

> /model claude-opus-4-8        # next request → anthropic-subscription
> /model MiniMax-M3-highspeed   # next request → minimax
> /model qwen3.6:35b            # next request → ollama-local

The matching is glob-based (claude-*, MiniMax-*, etc.) — patterns are declared per provider in the YAML. Unmatched model names fall through to default_provider.

Integrations

• Dark-factory ↔ claude-code-router — route YOLO container prompts through the host router for unified token storage + observability

Develop

make precommit   # gofmt, lint, vet, test, vulncheck, gosec, osv-scanner, trivy
make run         # run locally on 127.0.0.1:8788 with -logtostderr -v=2

License

BSD-2. See LICENSE.