A local Go gateway for explicit model selection, capability checks, and visible routing.
I’m actively working on Claude Code Router, an open-source project that connects Claude Code to first-party Anthropic models and configured external providers through a local gateway.
The command-line tool is called ccr. Claude Code connects to its loopback address, and CCR routes requests to the selected model. Supported provider profiles include OpenRouter, Z.AI, LiteLLM, and trusted local OpenAI-compatible endpoints. The gateway exits when the Claude Code process it launched exits.
This article walks through the project’s documented workflow: configure a provider, register model aliases, switch routes within a session, and inspect what happened. Project overview.
One session, explicit model selection
CCR separates a provider connection from a model alias. The connection defines the endpoint and credential source. The alias names a model route that you can select from Claude Code.
That separation lets a workflow keep using an alias while its configured provider model changes. In a session with preserved Claude authentication, eligible aliases appear alongside permitted Anthropic models in the /model picker. CCR also prints their exact picker IDs at launch.
Switching changes the route used for subsequent work where Claude Code permits it. New subagents and workflows can inherit the active model; existing workers can remain on their original model. Picker entries are generated at launch, so changes to aliases or capability metadata require a relaunch to refresh the visible choices. Routing documentation.
Selecting a registered CCR alias in /model and continuing the conversation. Cropped excerpt; 1.5× playback.
Compatibility is part of the route
CCR tracks provider and model capabilities before forwarding requests. Effective model facts follow a defined order: local overrides, provider discovery, then recognized model hints. Missing metadata remains unknown.
An imported model starts with degraded compatibility status. Importing it does not automatically certify every feature. Other statuses include full, chat-only, and blocked; a chat-only launch disables Claude Code tools, while blocked aliases are refused.
For example, the documented image-input path requires both a translatable image request and an effective capability allowing image input. If those conditions are not met, CCR rejects the request. It does not remove the image or silently send the request to another model.
OpenAI Responses support is also explicit. An OpenAI-compatible endpoint is not automatically treated as a Responses endpoint. The provider and alias must be configured for that route. Managed computer use adds another requirement: an explicitly selected supported executor.
These rules describe compatibility boundaries, not a promise that every provider implements every Claude Code feature. Provider and capability reference.
Getting started
Claude Code must already be installed and available as claude. On macOS, the documented Homebrew installation is:
brew install hishamkaram/tap/claude-code-router
ccr version
ccr doctor
ccr doctor checks the local setup; it is offline by default. Then configure a provider:
ccr init
ccr provider add --interactive
ccr model list
The wizard guides you through the provider profile, connection details, credential source, and model aliases. Providers with discovery expose a searchable model selection flow; other profiles use manual model entry. Nothing is saved until the final review completes.
With working Claude subscription or Anthropic API authentication, launch with:
ccr launch
To start on a configured provider alias, use:
ccr launch --model <alias>
Replace <alias> with a name from your model list. The default authentication mode preserves available Claude authentication. Without Claude authentication, an explicit provider alias allows a provider-only launch; omitting both causes launch to fail visibly. Getting-started guide.
Inspect the route, not the model’s self-description
CCR exposes commands for inspecting configuration, compatibility, and runtime activity:
ccr model show <alias> --json
ccr model test <alias>
ccr conformance run <alias>
ccr status
ccr trace --follow
The live checks contact the configured provider. Runtime records expose the observed alias, provider model, protocol, result, latency, and provider-reported token usage when available. CCR does not estimate monetary cost.
The routing documentation explicitly distinguishes those observations from a model’s generated answer about its own identity. A sentence in a conversation is not the route record. Runtime visibility.
Local state and credentials
CCR uses SQLite for configuration and redacted operational metadata. Its documented credential choices are environment-variable references, permission-restricted key files, and the OS keychain. Raw API keys are not stored in SQLite.
The documented route-history policy excludes prompts, responses, tool arguments, and authorization headers. Configuration exports also exclude credential values, keychain identifiers, and key-file paths; credentials are bound separately on the importing machine. Credential handling and team profiles.
Explore the project
Claude Code Router brings provider configuration, model selection, compatibility checks, and route inspection into one local tool. It is written in Go and released under the MIT license.
The repository includes installation instructions, release notes, and contribution guidelines. If you try a provider route, reproducible compatibility reports are welcome: include the CCR version, model alias, and redacted diagnostic output, without credentials or private prompts.
Originally published on Medium.
Disclosure: This article was drafted with AI using the linked repository documentation.
Top comments (0)