claude code router - Moses Yebei

Abstract

Use Claude Code as the foundation for coding infrastructure, allowing you to decide how to interact with the model while enjoying updates from Anthropic.

The Problem

Developers using Claude Code need a way to route requests to different LLM providers, apply request/response transformations, and manage models from the command line. Without a router they must edit Claude Code’s config manually or write ad‑hoc scripts, which is error‑prone and hard to version.

What This Does

claude-code-router sits between Claude Code and the underlying model APIs. It reads a JSON config (~/.claude-code-router/config.json) and, based on the request type, selects a provider (OpenRouter, Gemini, Ollama, etc.) and applies a transformer chain. The core logic lives in packages/core/src (transformers, plugin manager, server) while the CLI front‑end lives in packages/cli/src. The documentation site (docs/src/pages/index.tsx) and the example presets (examples/*.json) illustrate typical usage.

How It Is Wired

Entry point – the CLI is launched via packages/cli/src/cli.ts (main function, line 99).
main parses arguments (via @inquirer/prompts) and calls run in packages/cli/src/utils/index.ts (line 186).
run creates a readline interface, then invokes getServer from packages/server/src/index.ts.
getServer constructs an Express app (packages/core/src/server.ts:createApp) and registers routes from packages/core/src/api/routes.ts.
When a Claude Code request arrives, the route handler calls registerNamespace → initialize → registerDefaultTransformersInternal (see the call chain start → registerNamespace → initialize → registerDefaultTransformersInternal). This iterates Object.values(Transformers) and triggers each transformer (e.g., packages/core/src/transformer/anthropic.transformer.ts, openai.responses.transformer.ts).
The selected transformer calls the underlying model SDK (10 distinct functions across the repo, e.g., post in packages/server/src/index.ts). These are the only outward‑facing calls: they perform HTTP requests to provider endpoints.
After the model response returns, the transformer chain may modify the payload before the server sends it back to Claude Code.

Blast‑radius hotspots – packages/core/src/types/llm.ts and packages/core/src/types/transformer.ts are imported by 17 other modules each, making them high‑impact “hub” modules. The import cycle among packages/core/src/types/llm.ts, packages/core/src/types/transformer.ts, and packages/cli/src/utils/index.ts adds instability (instability = 1). The most‑connected functions (cn, delete, post) are called from dozens of places, so changes there ripple widely.

How To Use It

# 1. Install Claude Code (global)
npm install -g @anthropic-ai/claude-code

# 2. Install the router (global)
npm install -g @musistudio/claude-code-router

# 3. Create a config (example path shown in README)
cat > ~/.claude-code-router/config.json <<'EOF'
{
  "PROXY_URL": "http://127.0.0.1:7890",
  "LOG": true,
  "LOG_LEVEL": "debug",
  "APIKEY": "your-secret-key",
  "HOST": "127.0.0.1"
}
EOF

# 4. Start the router server (CLI command)
ccr start   # implemented in packages/cli/src/cli.ts

# 5. Switch models from Claude Code
/model gpt-4   # routed through the `/model` command handled by the transformer chain

All commands are documented under docs/docs/cli/commands/ and the example presets (examples/simple-preset-example.json) show how to declare provider‑specific settings.

Real‑World Use

A CI pipeline can run unit tests, then invoke ccr start in a Docker container (see packages/server/Dockerfile). A GitHub Action can call ccr model list to verify that the correct provider is selected before deploying code generation steps. Because the router logs both server‑level (pino files) and application‑level events, operators can audit which model answered a given request.

Code Health & Issues

High – Pin GitHub Actions – .github/workflows/* uses version tags (@v4, @v3). Replace with 40‑char commit SHAs to avoid supply‑chain attacks.
High – No test suite – 157 source files, 0 test files. Add at least one test per public entry point and run them in CI.
Medium – Enable Dependabot – No dependabot.yml; add to keep dependencies patched.
Medium – Use lockfile in CI – Workflows run npm install; switch to npm ci (or pnpm install --frozen-lockfile).
Medium – Pin Docker base image – node:20-alpine should be referenced by digest.
Medium – Add vulnerability scan – No dependency‑review step; integrate osv-scanner or dependency-review-action.
Medium – Checkout without persisting credentials – Add persist-credentials: false to the checkout step.
Medium – Run as non‑root – Dockerfile lacks a non‑root USER.
Low – Job timeouts – .github/workflows/docker-publish.yml omits timeout-minutes.
Low – Repository conventions – Missing .editorconfig, .gitattributes, and formatter config.

Additional observations: the repo includes a full Docusaurus site, Docker support, and CI, but lacks automated tests and some hardening best practices identified above.

The Bottom Line

claude-code-router provides a concrete, extensible way to route Claude Code requests across multiple LLM providers and apply custom transformations, with a clear CLI and server architecture. However, the lack of tests, the presence of import cycles, and several security‑hardening gaps mean the codebase needs prudent review before production deployment. It is suitable for teams comfortable tweaking TypeScript monorepos and willing to add the missing test and hardening steps.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

352 files

TypeScript113
Markdown93
TSX42
JSON35
JavaScript9
YAML5

ReactExpressTailwindDockerTransformers

Module dependencies

The 10 most depended-upon modules of 165, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_packages_core_src_types_llm["llm"] n1_s_core_src_types_transformer["transformer"] n2_ages_shared_src_preset_types["types"] n3_packages_cli_src_utils_index["index"] n4_ore_src_plugins_output_types["types"] n5_ges_core_src_services_config["config"] n6_rc_components_ConfigProvider["ConfigProvider"] n7_s_cli_src_utils_processCheck["processCheck"] n8_cli_src_utils_preset_install["install"] n9_kages_core_src_plugins_types["types"] n3_packages_cli_src_utils_index --> n7_s_cli_src_utils_processCheck n7_s_cli_src_utils_processCheck --> n3_packages_cli_src_utils_index n0_packages_core_src_types_llm --> n1_s_core_src_types_transformer n1_s_core_src_types_transformer --> n0_packages_core_src_types_llm classDef cyc stroke:#ef4444,stroke-width:2px; class n0_packages_core_src_types_llm,n1_s_core_src_types_transformer,n3_packages_cli_src_utils_index,n7_s_cli_src_utils_processCheck cyc;

Dependencies

10 of 27 declared dependencies are a major version behind. Resolved 25 of 27 against the registry.

Package	Declared	Latest	Behind
`@inquirer/prompts`	^5.0.0	8.5.2	3 major
`@types/node`	^24.0.15	26.2.0	2 major
`typescript`	^5.8.2	7.0.2	2 major
`react`	^18.3.1	19.2.8	1 major
`react-dom`	^18.3.1	19.2.8	1 major
`@types/react`	18	19.2.18	1 major
`@types/react-dom`	18	19.2.4	1 major
`tailwindcss`	3	4.3.3	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium6

low2

Pin third-party GitHub Actions to a commit SHAhigh5 occurrences

.github/workflows

pnpm/action-setup@v4, docker/setup-buildx-action@v3, docker/login-action@v3, docker/metadata-action@v5

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a test suite; this repository has nonehigh157 occurrences

157 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Enable Dependabot or Renovatemedium

7 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Install from the lockfile in CImedium

.github/workflows

npm install with a committed package-lock.json

A fresh resolution in CI means the tested dependency set is not the locked one, so the failure only appears after merge.

Fix: Use npm ci, yarn install --immutable, or pnpm install --frozen-lockfile.

Pin the container base image by digestmedium2 occurrences

packages/server/Dockerfile

node:20-alpine, node:20-alpine

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/docker-publish.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

packages/server/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/docker-publish.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.