Claude Code on OpenRouter — LTS Installer

Run the official Claude Code CLI and VS Code extension through any OpenRouter model, without losing tools, file editing, bash, MCP, or repo workflow.

Quick Start

# 1. Install official Claude Code (only if missing)
curl -fsSL https://claude.ai/install.sh | bash

# 2. Clone this repo
git clone https://github.com/allytag/Claude_Code.git 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 status

That's it. Claude Code now runs on your chosen OpenRouter model with full tool access.

Why This Exists

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 (observed 57% turn-2 cost drop on Kimi+Novita)
Auto-updates can break your custom config	Updates frozen by default; `claude-safe-update` is the manual audited path
Good code but weak UI/design output	Bundled Claude Code Skills, slash commands, statusline, and subagents for design, review, architecture, debug, security, performance, tool discipline, and shipping
Skills may become insufficient over time	Skill inbox + guard pipeline drafts, validates, and promotes new skills only after approval
Setup state spread across many files	Single registry + doctor + cleanup tool

What's Included

Feature	What it does
Original Claude Code	Official CLI preserved; VS Code extension patched reversibly for OpenRouter compatibility. 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.
Failure handling	Logs finish reasons and retries transient provider failures once (`429`, `502`, timeout/fetch errors) before surfacing failure.
Power Pack	Installs focused Claude Code Skills, agents, and slash commands for context scouting, premium UI, SaaS architecture, API contracts, testing, security, performance, project memory, agent bootstrap, tool coaching, debugging, and release checks.
Skill evolution guard	New skills are drafted into `~/.claude/skill-inbox`, checked by `skill-guard.mjs`, and promoted only with explicit `--apply`.
Statusline	Shows active OpenRouter role/model, provider, last cost, tokens, cache, finish reason, retry count, and compact hints without model calls.
Doctor + cleanup	Health, drift detection, cache readiness, stale-data cleanup. Caveman/Desktop/projects protected.
Frozen updates	CLI auto-updater and VS Code extension update checks disabled. `claude-safe-update` snapshots, patches, validates, restores on failure.
LTS env injection	Wrappers boot-resilient. Survives reboots, fresh shells, OS updates.

Comparison

	Raw Claude Code (Anthropic)	Raw OpenAI gateway	This setup
Tools, file edit, MCP	✅	⚠️ varies	✅ 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
Skills / subagents	✅	varies	✅ installed + OpenRouter-routed
No vendor lock-in	❌	partial	✅ swap any OpenRouter model

Requirements

See Platform Status before installing.

Required

macOS Apple Silicon (M-series) for LTS installer
Node.js ≥ 20
Zsh
Official Claude Code CLI (install)
OpenRouter API key

Optional

VS Code + the official anthropic.claude-code extension

If VS Code is missing the installer skips that step and continues CLI-only.

Platform Status

Platform	Status	Installer	Notes
macOS Apple Silicon	LTS	`./install.sh`	Primary supported path. Uses LaunchAgent and macOS VS Code paths.
Linux	Beta	`node platforms/linux/install.mjs`	Isolated support path using `systemd --user`.
Windows	Beta	`node platforms/windows/install.mjs`	Isolated support path using `.cmd` wrappers and optional Task Scheduler.

The macOS installer flow is not shared with beta platform installers. Linux/Windows support can grow without changing the locked macOS LTS path.

Install

Quick install (default, recommended)

git clone https://github.com/allytag/Claude_Code.git Claude && cd Claude
./install.sh --dry-run     # always preview first
./install.sh --merge       # prompts for OpenRouter key, hidden input

The --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_KEY

Fresh install (empty target only)

./install.sh --fresh       # refuses if ~/.claude already has setup

Upgrade existing install

git pull
./install.sh --dry-run
./install.sh --upgrade     # preserves token + role choices

See docs/UPDATE.md.

Daily Commands

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`
List installed Skills/agents/commands	`ls ~/.claude/skills ~/.claude/agents ~/.claude/commands`

Built-in Power Commands

Command	Use case
`/smart-plan`	Compact implementation plan before coding
`/context-scout`	Find relevant files without dumping whole repo
`/ui-polish`	Premium UI pass for pages/components
`/ship-feature`	Plan → implement → test workflow
`/debug-loop`	Evidence-first bug fix workflow
`/release-check`	Final ship/no-ship review
`/security-audit`	Security-focused read-only audit
`/skill-forge`	Draft guarded skill upgrades into inbox
`/tool-coach`	Choose safest tool sequence before work

Full daily workflow in docs/INSTALL.md.

Default Model Roles

main      → moonshotai/kimi-k2.6        (observed 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           (manual fallback role; installed agents use frontmatter policy)
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. Installed agents use their own model frontmatter, so CLAUDE_CODE_SUBAGENT_MODEL stays unset by default. Change any role with claude-router use <role> <alias>. Apply to settings with claude-router apply-settings.

Architecture (one diagram)

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.

Safety Guarantees

✅ 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-backup rolls back.

Threat model and what's protected vs. not: docs/SECURITY.md.

FAQ

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 machine. 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?

Linux and Windows support exists in isolated beta folders:

node platforms/linux/install.mjs --dry-run --merge

node platforms/windows/install.mjs --dry-run --merge

These installers are isolated from the macOS LTS flow and include dry-run preflight checks.

How do I uninstall?

./uninstall.sh                       # removes proxy, wrappers, LaunchAgent
./uninstall.sh --restore-last-backup # rolls back to pre-install state

Claude Code itself stays installed.

Troubleshooting

Common fixes in docs/TROUBLESHOOTING.md. Doctor and verify scripts cover most cases:

./verify.sh
node ~/.claude/openrouter-claude-proxy/doctor.mjs

Documentation

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

License

MIT. See LICENSE.

Contributing

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

claude_code