claude-code-router

README

Claude Code Router

ccr is a local gateway for using Claude Code with first-party Anthropic models and configured third-party model providers in one session. It keeps Claude Code connected to one loopback-only gateway while routing each request to the selected model safely and visibly.

CCR is built for users who want to keep Claude Code's normal workflow while adding providers such as OpenRouter, Z.AI, LiteLLM, or a local OpenAI-compatible endpoint. It never silently falls back to a different model or provider.

Install

Homebrew (macOS)

brew install hishamkaram/tap/claude-code-router

GitHub Releases (macOS and Linux)

Download the archive for your operating system and CPU from the latest release, verify it against checksums.txt, then place ccr on your PATH.

tar -xzf <downloaded-archive>.tar.gz
mkdir -p ~/.local/bin
install -m 755 ccr ~/.local/bin/ccr
ccr version

Go

Install from source with Go 1.25 or newer:

go install github.com/hishamkaram/claude-code-router/cmd/ccr@latest
ccr version

Requirements

• Claude Code must be installed and available as claude.
• Sign in to Claude Code when you want to use first-party Anthropic routes.
• Set any external-provider credentials in environment variables, a 0600 key file, or the OS keychain. CCR never stores raw API keys in SQLite.

Run this after installation to check the local setup:

ccr doctor

Quick Start

The guided path is the shortest way to add a provider, choose credentials, import models, and review aliases before anything is saved.

ccr init
ccr provider add --interactive
ccr model list
ccr launch

ccr launch keeps Claude Code's normal startup model, preserves subscription authentication, and adds safe registered aliases to the /model picker beside the permitted Anthropic models. CCR also prints each picker ID, such as /model anthropic.ccr.<alias>, for scripted selection. To start directly on one alias, including a chat-only alias that disables tools for the launch, pass it explicitly:

ccr launch --model <alias> --chrome

Scripted Setup

For automation, add providers and models without prompts:

export OPENROUTER_API_KEY='replace-with-your-key'

ccr provider add openrouter --api-key-env OPENROUTER_API_KEY
ccr provider test openrouter
ccr provider import-models openrouter --all

Or import with the searchable review flow:

ccr provider import-models openrouter

For providers without model discovery, add aliases explicitly:

ccr model add coding-model --provider openrouter --model <provider-model-id>
ccr model test coding-model

Your organization may restrict which Claude Code model options are available; CCR reports that limitation instead of bypassing it.

How Routing Works

1. CCR launches Claude Code through a loopback-only local gateway.
2. Default subscription-preserving launches add registered, non-blocked, tool-compatible aliases to the /model picker. Tool-disabled aliases are available by starting directly with ccr launch --model <alias>.
3. Standard first-party model names route to Anthropic. The default --auth-mode preserve keeps an existing Claude Code subscription login or Anthropic API-key authentication available for those routes.
4. CCR checks provider capabilities before a request is sent. Unsupported or unsafe behavior is rejected with an explanation; it is never redirected to Claude or another configured provider.

Model self-identification is generated text, not proof of routing. When an OpenAI-compatible model is asked which model is active, CCR adds route context so the answer can reflect the current alias and provider model instead of an older turn from the same Claude Code session.

Use ccr launch --auth-mode gateway-token --model <alias> when you want a third-party-only session. That mode intentionally disables the original Anthropic subscription and API-key authentication. It also lets Claude Code authenticate to CCR's /v1/models endpoint for friendly discovery metadata. Current Claude Code auto mode may require first-party Anthropic access for its safety classifier, so use the default --auth-mode preserve for Agent or Workflow actions. CCR surfaces classifier denial instead of bypassing it.

Common Commands

ccr provider list                 # show configured providers
ccr model list                    # show model aliases
ccr model test <alias>            # validate a route against its provider
ccr conformance run <alias>       # record compatibility checks
ccr launch                        # preserve subscription; expose aliases in /model
ccr launch --model <alias>        # start directly on one CCR alias
ccr status                        # show the latest observed route and health
ccr trace --follow                # follow redacted route and lifecycle events
ccr sessions --active             # list active launches and Claude sessions
ccr agents --active               # list active agents, teammates, and tasks
ccr doctor --live                 # probe one model per configured provider
ccr profile export team.json      # export routing config without credentials

ccr status, ccr trace, ccr sessions, and ccr agents also support stable schema_version: 1 JSON output. Launches inject a compact CCR status line and Claude lifecycle hooks for that process only. Existing status-line and hook configuration is preserved. Use --no-statusline, --no-lifecycle, or --no-history to disable those features independently for one launch.

Team Profiles

Export provider and model routing configuration for another machine without exporting credentials:

ccr profile export team.json
ccr profile import team.json --dry-run
ccr profile import team.json --credential openrouter=OPENROUTER_API_KEY

Profiles may carry environment-variable names, but never raw secret values, keychain identifiers, or credential-file paths. Imports are validated and applied atomically; conflicts fail without partial changes.

Documentation

• Getting started
• Providers and model aliases
• Routing, authentication, and compatibility
• Troubleshooting
• Maintainer release process

Security and Local State

CCR stores provider configuration, model aliases, redacted route history, hook-observed lifecycle state, and compatibility metadata in a local SQLite database. By default it uses $XDG_DATA_HOME/claude-code-router/ccr.db, or ~/.local/share/claude-code-router/ccr.db when XDG_DATA_HOME is unset. Use --db <path> to keep state elsewhere.

SQLite contains only secret references such as env:OPENROUTER_API_KEY, never the API-key value. Route history never stores prompts, responses, tool arguments, hook bodies, transcript paths, or authorization headers. CCR records provider-reported token usage when available but does not estimate monetary cost. See provider credential handling for the supported secret sources.

Development

make build
make test
make check
make test-live-fixture
CCR_LIVE_REAL_MATRIX=1 make test-live-real

The required fixture target needs an installed Claude Code CLI but no provider credential. CI runs it without skips through OpenAI-compatible and Anthropic-compatible fixtures against pinned Claude Code 2.1.209 and the latest npm release. The real target uses first-party Anthropic authentication and every configured non-blocked alias in the selected database. A skipped live test is not equivalent to a verified runtime route.

Contributing and Security

Read CONTRIBUTING.md before opening a pull request. Report security vulnerabilities privately as described in SECURITY.md.

License

MIT. See LICENSE.