Run the official Claude Code CLI and VS Code extension through any OpenRouter model, without losing tools, file editing, bash, MCP, or repo workflow.
# 1. Install official Claude Code (only if missing)
curl -fsSL https://claude.ai/install.sh | bash
# 2. Clone this repo
git clone <your-repo-url> Claude && cd Claude
# 3. Preview what will happen (no writes)
./install.sh --dry-run
# 4. Install (prompts for OpenRouter key, hidden input)
./install.sh --merge
# 5. Use it
claude # full Claude Code, routed through OpenRouter
claude-router statusThat's it. Claude Code now runs on your chosen OpenRouter model with full tool access.
| Problem | This installer's answer |
|---|---|
| Claude Code is locked to Anthropic's billing | Routes through OpenRouter to any compatible model |
| Custom-model setups break Claude Code's tools/file editing | Preserves the full agentic protocol — no compromise mode |
| Hidden reasoning tokens silently inflate cost | Strips reasoning fields by default, registry-gated pass-through for hard tasks |
| No cache → 24 K-token floor on every turn | Auto-injects cache markers + provider pinning (proven 57% turn-2 cost drop on Kimi+Novita) |
| Auto-updates can break your custom config | claude-safe-update with CLI + extension snapshots, validation, rollback |
| Setup state spread across many files | Single registry + doctor + cleanup tool |
| Feature | What it does |
|---|---|
| Original Claude Code | CLI + VS Code extension untouched. All tools, file edits, bash, repo, MCP work. |
| Local proxy | Anthropic-compatible endpoint at 127.0.0.1:4141, forwards to OpenRouter. Strips thinking fields, sanitizes responses. |
| Model registry | Roles (main / cheapFull / hard / subagent / lowToken / backup / compare) → OpenRouter model IDs. Swap any time. |
| Smart caching | Auto-inject Anthropic cache_control markers. Provider pinning via registry to keep cache continuity. |
| Internal Haiku remap | Claude Code's silent background Haiku calls re-routed to your cheapFull model. Safety-gated (no tools, ≤2 messages). |
| Reasoning policy | Reasoning passes through only for registry-allowlisted models on /effort high. Others stripped to prevent surprise cost. |
| Doctor + cleanup | Health, drift detection, cache readiness, stale-data cleanup. Caveman/Desktop/projects protected. |
| Safe updates | claude-safe-update snapshots CLI + VS Code extension, runs official installers with timeout, patches, validates, restores on failure. |
| LTS env injection | Wrappers boot-resilient. Survives reboots, fresh shells, OS updates. |
| Raw Claude Code (Anthropic) | Raw OpenAI gateway | This setup | |
|---|---|---|---|
| Tools, file edit, MCP | ✅ | ✅ preserved | |
| OpenRouter custom models | ❌ | ❌ | ✅ |
| Anthropic prompt cache | ✅ | ❌ | ✅ (provider-dependent) |
| Provider pinning | ❌ | ❌ | ✅ |
| Update safety | manual | manual | ✅ snapshot+rollback |
| Cost guard / metrics | partial | none | ✅ privacy-safe metrics |
| No vendor lock-in | ❌ | partial | ✅ swap any OpenRouter model |
Required
- macOS Apple Silicon (M-series)
- Node.js ≥ 20
- Zsh
- Official Claude Code CLI (install)
- OpenRouter API key
Optional
- VS Code + the official
anthropic.claude-codeextension
If VS Code is missing the installer skips that step and continues CLI-only.
Quick install (default, recommended)
git clone <your-repo-url> Claude && cd Claude
./install.sh --dry-run # always preview first
./install.sh --merge # prompts for OpenRouter key, hidden inputThe --merge mode preserves any existing ~/.claude/settings.json keys (MCP, hooks, plugins, your token) and only writes what's needed.
Non-interactive install (CI / scripted)
read -s OPENROUTER_API_KEY # paste key, hidden
./install.sh --merge --api-key-env OPENROUTER_API_KEY --yes
unset OPENROUTER_API_KEYFresh install (empty target only)
./install.sh --fresh # refuses if ~/.claude already has setupUpgrade existing install
git pull
./install.sh --dry-run
./install.sh --upgrade # preserves token + role choicesSee docs/UPDATE.md.
| Task | Command |
|---|---|
| Use Claude Code (full mode) | claude |
| Live token/cost tail | claude-router tail |
| System health | claude-router status |
| List models in registry | claude-router list |
| One-off model test (no role change) | claude-model kimi-k2.6 -p "say hi" |
Switch the main role |
claude-router use main deepseek-v4-pro |
| Add a new OpenRouter model | claude-router add grok x-ai/grok-4 --name "Grok 4" |
| Low-token Q&A (no tools) | claude-low "explain debounce" |
| Cleanup stale data (dry-run first) | claude-router cleanup all-safe |
| Cleanup apply | claude-router cleanup all-safe --apply |
| Update Claude Code safely | claude-safe-update latest --dry-run then claude-safe-update latest |
| Run doctor | node ~/.claude/openrouter-claude-proxy/doctor.mjs |
Full daily workflow in docs/INSTALL.md.
main → moonshotai/kimi-k2.6 (proven cache; Novita pin)
cheapFull → qwen/qwen3.6-plus (cheap, large context)
hard → deepseek/deepseek-v4-pro (manual; reasoning passes through)
subagent → qwen/qwen3.6-plus
lowToken → qwen/qwen3.6-plus
backup → deepseek/deepseek-v4-pro
compare → z-ai/glm-5.1
Roles map to Claude Code's sonnet / haiku / opus slots automatically. Change any role with claude-router use <role> <alias>. Apply to settings with claude-router apply-settings.
flowchart LR
A[claude / VS Code ext] -->|HTTP| P[127.0.0.1:4141<br/>local proxy]
P -->|sanitize<br/>cache_control<br/>provider pin<br/>haiku remap| OR[OpenRouter<br/>Anthropic-compatible]
OR --> M1[Kimi K2.6 / Novita]
OR --> M2[Qwen 3.6 / Alibaba]
OR --> M3[DeepSeek V4 / AtlasCloud]
OR --> M4[your future model]
Full design in docs/ARCHITECTURE.md.
- ✅ Never touches Claude Desktop, caveman plugin, unrelated projects.
- ✅ No API key in this repo. Redaction check enforced (
scripts/redact-check.mjs). - ✅ No model calls during install or doctor (unless you opt in with
--probe --allow-model-call). - ✅ All edits backed up to
~/.claude/installer-backups/openrouter-lts-<stamp>/. - ✅ Idempotent — re-running install is safe.
- ✅ Reversible —
./uninstall.sh --restore-last-backuprolls back.
Threat model and what's protected vs. not: docs/SECURITY.md.
Will this break Claude Code's tools, file edits, or MCP?
No. Full Claude Code mode is preserved — same tool contract, same protocol, same UI. The proxy only sanitizes thinking blocks and adds cache markers; tool calls and tool results pass through untouched. Verified by file-edit smoke test.
Does my OpenRouter key end up in the repo?
No. The installer prompts for it (hidden input) and writes it only to ~/.claude/settings.json on the target Mac. The repo's redaction check refuses any commit containing sk-or- or a real auth token.
What about Claude Desktop / Anthropic billing?
Untouched. The installer detects and reports Claude Desktop but never modifies it. Your Claude Desktop subscription, login, and config are unaffected.
How much does it actually save?
On Kimi K2.6 + Novita pinning: turn 2 of any session drops from $0.020 → $0.009 (57% cheaper) once cache warms. Verified with real OpenRouter calls.
What if a Claude Code update breaks something?
claude-safe-update snapshots the current CLI binary and Claude Code VS Code extension, runs the official update steps with a timeout, patches the extension, validates the full stack (size, executable, version check, doctor, proxy health, extension patch), and restores snapshots if any critical check fails. You always have a known-good rollback.
Can I add a new OpenRouter model later?
Yes. claude-router add <alias> <provider/model-id> --name "Display Name", then claude-router use <role> <alias> to assign it. No re-install needed.
Linux or Windows support?
Not yet. macOS Apple Silicon only. Path layouts and launchctl are macOS-specific. Contributions welcome.
How do I uninstall?
./uninstall.sh # removes proxy, wrappers, LaunchAgent
./uninstall.sh --restore-last-backup # rolls back to pre-install stateClaude Code itself stays installed.
Common fixes in docs/TROUBLESHOOTING.md. Doctor and verify scripts cover most cases:
./verify.sh
node ~/.claude/openrouter-claude-proxy/doctor.mjs| File | Topic |
|---|---|
| docs/INSTALL.md | Step-by-step install + daily workflow |
| docs/ARCHITECTURE.md | Request flow, components, design decisions |
| docs/SECURITY.md | Threat model, redaction, what's protected |
| docs/UPDATE.md | Safe Claude CLI updates, repo upgrades |
| docs/TROUBLESHOOTING.md | Problem → fix pairs |
MIT. See LICENSE.
Issues and PRs welcome. Before committing, run:
node scripts/redact-check.mjs # blocks any secret leak
node scripts/build-manifest.mjs # refreshes file hashes
./verify.sh # full repo self-check