cc-mirror: isolated, provider-native Claude Code variants with pinned runtimes

What cc-mirror creates and why isolation is the point

cc-mirror is a Node CLI published to npm as `cc-mirror`, version 2.2.3, MIT licensed. The README calls it an opinionated provider-native coding distribution, and the useful way to read that is isolation plus defaults. Each variant gets its own runtime installation, its own config directory holding API keys, sessions and MCP servers, its own tweakcc theme directory, and a `variant.json` metadata file. The main installation is left alone.

That is the whole design in one sentence, and it is a design more tools in this space get wrong. Configuring a second provider usually means editing shared config, and the failure mode is discovering three weeks later that an experiment silently repointed your working setup. Here the failure mode is contained by construction.

The fastest path is two commands:

npx cc-mirror quick --provider mirror --name mirror

and then running the generated wrapper, which is just `mirror`. There is also a full interactive wizard launched with a bare `npx cc-mirror`. The `quick` subcommand exists precisely so you can skip the wizard when you already know what you want, which tells you something about who this is for.

The directory layout is documented as a diagram, and the important part is what sits above it: `~/.cc-mirror/` holds one directory per variant, and wrappers go into a bin directory that defaults to `~/.local/bin` on macOS and Linux and `~/.cc-mirror/bin` on Windows. On Windows the README advises adding that bin path to PATH or running the `.cmd` wrapper directly, and notes every wrapper has a sibling `.mjs` launcher.

Runtime versions: channels resolved at install and stored in variant.json

By default cc-mirror installs the latest native runtime release, but you can pin a channel or an exact version:

npx cc-mirror quick --provider mirror --name mirror --claude-version stable

The upstream channels are `stable` and `latest`, and the README is candid that stable may lag behind latest, calling that normal rather than a defect. Exact versions work too, with a concrete example given: `npx cc-mirror update mirror --claude-version 2.1.37`.

The mechanism worth noting is that cc-mirror resolves a channel to a concrete version during install or update and then stores that resolved version in `variant.json`. So a variant created against today's `stable` is not a moving target: the resolution happens once and the concrete version is recorded. That is a small design decision with a large effect on reproducibility, and it is the kind of thing that only matters if you have been burned by a tool that silently upgraded underneath you.

The update path is where the maintainers put the most explicit prose, which suggests it is where the pain was. `npx cc-mirror update [name]` refreshes the native runtime and the cc-mirror-managed defaults for that variant, and the list of what it touches is explicit: provider endpoints, model slots, update and install and privacy flags, provider-managed MCP servers, and managed tweakcc startup and banner settings. Credentials and custom environment keys are preserved. The boundary matters, so restate it: managed configuration is overwritten, secrets are not.

Nine providers, and what the routing table is actually for

The provider table is the part of the README most likely to age, and it is worth reading as a snapshot rather than a contract. Kimi is listed with the `kimi-for-coding` model for long-context coding. MiniMax maps to M2.7. Z.ai offers GLM-5.1, 5-Turbo and 4.5-Air for reasoning-heavy work. OpenRouter is the flexible option with 100+ models on pay-per-use billing. Vercel is a multi-provider gateway via the Vercel AI Gateway. Ollama covers local and cloud models for hybrid setups. NanoGPT is listed with GPT-5.2 and Gemini 3 Flash. CCRouter covers Ollama and DeepSeek for local-first development. GatewayZ is described as a multi-provider gateway for centralized routing.

The default deserves separate attention because it is the least interesting row and the most useful one. The `mirror` provider is described as the clean default runtime path with no proxy and no model changes, just isolation and privacy defaults. You authenticate normally inside the isolated config. If you are evaluating cc-mirror at all, start there, because it is the configuration where the tool does the one thing it does that nothing else does and nothing can break.

Managed variants also ship with several opinionated defaults that you should confirm you want: cc-mirror-controlled updates, disabled upstream install checks, privacy-oriented hosted-provider traffic settings, and hidden upstream startup branding where tweakcc can control it. That last one is the item to think about. Hiding a vendor's branding is not a technical requirement, and if you run this in a workplace you should be comfortable explaining it.

MCP servers and the scope flag that actually changes behaviour

Each variant has its own Claude Code config directory, so MCP servers are added per variant at `~/.cc-mirror/<variant>/config/.claude.json`. cc-mirror keeps provider-managed MCP servers current during an update while preserving unrelated user-added servers in the same file, which is the right behaviour for a file that accumulates hand edits.

The scope flag is where most people lose an afternoon, and the README explains it properly. The command shape takes a provider wrapper, a subcommand and a JSON definition:

openrouter mcp add-json airtable '{"command":"npx","args":["@rashidazarang/airtable-mcp"],"env":{"AIRTABLE_TOKEN":"","AIRTABLE_BASE_ID":""}}' --scope user

Pass `--scope user` and the server loads in every project for that one variant. Pass `--scope project` and Claude Code writes a `.mcp.json` into the project. The README also flags the trap in the default local scope: it is project-specific but private, so a server added from one working directory may not appear from another. That is a Claude Code behaviour rather than a cc-mirror one, but cc-mirror is the layer where you will hit it.

Worth noting that the servers here are namespaced to a variant. Because `openrouter` and `zai` are separate wrappers with separate config directories, the same MCP server can be configured differently per provider. That is a genuine consequence of the isolation design rather than a documented feature, and it is probably the thing you will end up using.

The release notes reveal where this project actually has trouble

The version history is the best documentation in the repository, and reading it top down tells you what to be careful about. v2.2.3, published 2026-05-31, is almost entirely about Kimi and Windows. Kimi variants now use the Kimi Code endpoint and model defaults. Windows creation and update flows stay usable when tweakcc cannot validate a patched Claude Code binary, with cc-mirror falling back to the pristine native runtime instead of aborting. Windows end-to-end release checks were repaired for the hidden-version default.

v2.2.2, released roughly an hour earlier the same day, is where the Kimi routing changed: the Kimi provider is routed through the Kimi Code subscription endpoint at `https://api.kimi.com/coding` with the `kimi-for-coding` model, plus a required `User-Agent: KimiCLI/1.5` custom header. That an authenticated third-party endpoint needs a spoofed user agent header is a reasonable signal about how brittle these integrations are.

Two patterns emerge. Provider integrations are fragile and get patched reactively, and Windows is where the binary-patching assumption breaks most often. The fallback behaviour in v2.2.3 is the right call, degrading to an unpatched runtime rather than refusing to work.

The repository itself is a well-organised TypeScript project rather than a shell script collection. The tree includes `src/`, `test/`, `scripts/`, `docs/` and a `DESIGN.md`, with `lefthook.yml` for git hooks and `.c8rc.json` for coverage configuration. `package.json` shows the whole quality chain in one place: `npm run check` runs typecheck, then lint, then test with coverage, then bundle. The published package ships only `dist`, and there is a `tui` script driving an Ink-based terminal interface, with `ink`, `ink-select-input`, `ink-text-input` and `react` as the only runtime dependencies. The repository is not archived, MIT licensed, with 8 open issues, 2,263 stars and 291 forks, last pushed 2026-05-31.

Editorial conclusion

cc-mirror solves a specific and unglamorous problem: you want to try a second provider behind Claude Code without touching the install you depend on. The per-variant directory layout answers that properly, with its own config, sessions, MCP servers and credentials, and the update path that preserves credentials while refreshing endpoints and model slots is the part that makes variants long-lived rather than disposable. Two things to know before you commit. It is issues-first, and the README states plainly that external pull requests are not accepted directly, so your route in is an issue with provider docs and reproduction steps. And it depends on a binary-patching tool called tweakcc to hide upstream branding and control startup behaviour, which the release notes show is not always available, most visibly on Windows where recent versions fell back to the pristine native runtime instead of aborting. Start with the mirror provider and no proxy, since that path changes nothing about your models, then read the update policy before you add credentials.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. numman-ali/cc-mirror on GitHub
4. README
5. Releases