DOCSEARCHbyAlgolia
Submit Docs

cc-mirror

repository·main·Indexed 24 days ago

https://github.com/numman-ali/cc-mirror

An opinionated provider-native coding distribution that creates isolated runtime instances for different AI providers such as Kimi, MiniMax, Z.ai, OpenRouter, Vercel, Ollama, NanoGPT, and GatewayZ. It automates the configuration of endpoints, model slots, and prompt packs to provide a plug-and-play coding environment. Version 2.2.3 supports custom providers, tweakcc theming, and version tracking (stable, latest, or pinned) for the native runtime.

Tokens
22.3K
Snippets
21
Records
135
Agent score
80%

What's inside cc-mirror

  1. Overview of CC-MIRROR

    main
    CC-MIRROR is a tool designed to create multiple isolated coding variants using custom providers. It allows developers to switch between different LLM providers (such as Kimi, Minimax, Zai, OpenRouter, etc.) to create specialized coding environments with specific models, authentication modes, and prompt packs.

  2. How CC-MIRROR works: System Overview

    main

    CC-MIRROR operates through a three-tier architecture:

    1. CLI / TUI: The user interface layer (Command Line Interface or Terminal User Interface) where users issue commands.
    2. Core Engine: The central logic that manages Providers (templates for different AI services) and Brands (visual theme presets).
    3. Variant Directory: The persistent storage layer located at ~/.cc-mirror/<name>/. This directory contains the configuration and files for a specific variant.

    The engine generates a Shell Wrapper in a binary directory (defaulting to ~/.local/bin on macOS/Linux or ~/.cc-mirror/bin on Windows) which points to the native Claude Code binary, allowing users to interact with their configured variant directly via the terminal.

  3. Understand the Variant Directory Structure

    main

    Each CC-MIRROR variant is stored in a dedicated directory under ~/.cc-mirror/<variant>/. This directory contains the native Claude Code installation, configuration files, and customization settings.

    Directory Layout:

    • native/: Contains the claude binary.
    • config/: The CLAUDE_CONFIG_DIR. Contains settings.json (environment variables like API keys and base URLs) and .claude.json (MCP servers, approvals, and onboarding).
    • tweakcc/: Configuration for UI and theme customization via tweakcc. Includes config.json and system-prompts/ for prompt pack overlays.
    • variant.json: Metadata describing the specific variant.
    • Wrapper: A shell script located in your <bin-dir>/ that allows you to run the variant as a standalone command.
    ┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  ~/.cc-mirror/<variant>/                                                    │
│                                                                             │
│  ├── native/                        Claude Code native installation         │
│  │   ├── claude                      Claude Code binary                     │
│  │                                                                          │
│  ├── config/                         CLAUDE_CONFIG_DIR                      │
│  │   ├── settings.json              Env vars (API keys, base URLs)          │
│  │   ├── .claude.json               MCP servers, approvals, onboarding      │
│  │                                                                          │
│  ├── tweakcc/                        tweakcc configuration                  │
│  │   ├── config.json                Theme and UI customization              │
│  │   ├── cli.js.backup              tweakcc-managed backup                  │
│  │   └── system-prompts/            Prompt pack overlays                    │
│  │                                                                          │
│  └── variant.json                    Variant metadata                       │
│                                                                             │
│  Wrapper: <bin-dir>/<variant>        Shell wrapper script                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

  4. The Variant Lifecycle: Create and Update flows

    main

    CC-MIRROR manages the lifecycle of a 'variant' (a specific configuration of a provider and brand) through two primary automated flows:

    Create Flow

    When running npx cc-mirror create, the engine performs the following steps:

    1. Parse Args: Processes --provider, --name, and --api-key.
    2. Resolve Provider: Fetches the template from the provider registry.
    3. Build Steps:
      • PrepareDirectoriesStep: Creates ~/.cc-mirror/<name>/.
      • InstallNativeStep: Downloads and verifies the native Claude Code binary.
      • WriteConfigStep: Writes settings.json and .claude.json.
      • BrandThemeStep: Writes tweakcc/config.json.
      • TweakccStep: Applies customizations via tweakcc.
      • WrapperStep: Creates the executable in the <bin-dir>/<name>.
      • ShellEnvStep: (Optional) Updates shell profile environment variables.
      • SkillInstallStep: (Optional) Installs dev-browser skills.
      • FinalizeStep: Writes variant.json metadata.

    Update Flow

    When running npx cc-mirror update <name>, the engine reads the existing variant.json and executes these steps:

    1. RebuildUpdateStep: Resets claude/tweakcc directories while preserving configuration.
    2. InstallNativeUpdateStep: Re-verifies the native Claude Code binary.
    3. ModelOverridesStep: Updates model mappings.
    4. TweakccUpdateStep: Re-applies the chosen theme.
    5. WrapperUpdateStep: Regenerates the shell wrapper script.
    6. ConfigUpdateStep: Updates settings.json.
    7. ShellEnvUpdateStep: Updates shell environment integration.
    8. SkillInstallUpdateStep: Updates installed skills.
    9. FinalizeUpdateStep: Updates the variant.json metadata.

  5. How cc-mirror uses tweakcc for patching

    main

    cc-mirror integrates tweakcc to customize Claude Code variants. It manages configuration and system prompts in specific directories for each variant and applies patches to the native Claude Code binary.

    Configuration Locations

    • tweakcc config: ~/.cc-mirror/<variant>/tweakcc/config.json
    • system prompts: ~/.cc-mirror/<variant>/tweakcc/system-prompts/
    • Claude settings: ~/.cc-mirror/<variant>/config/settings.json (used for permissions.deny to enforce tool restrictions)

    Patching Behavior

    • cc-mirror applies tweakcc patches automatically during creation or updates, unless the --no-tweak flag is used.
    • To re-apply patches to an existing variant without a full reinstallation, use: npx cc-mirror apply <variant>
    • cc-mirror pins a specific tweakcc version for reproducibility, but will retry with tweakcc@latest if it cannot extract a newer Claude Code native binary.

  6. How the cc-mirror Provider System works

    main

    cc-mirror uses a template-based system to model each provider. A provider template defines the core connectivity and behavior for a specific service, including its base URL, auth mode, default model slots (Primary/Balanced/Fast), and UI elements like variant wrapper splash and labels.

    This system ensures predictable provider wiring while allowing users to override any setting via settings.json.

    Key architectural locations:

    • Provider definitions: src/providers/index.ts
    • Brand presets (tweakcc config): src/brands/*.ts
    • Brand resolution: src/brands/index.ts
    • Prompt-pack overlays: src/core/prompt-pack/providers/

  7. Configure MCP Servers for a Variant

    main

    Each CC-MIRROR variant maintains its own isolated Claude Code configuration. To add MCP (Model Context Protocol) servers that apply specifically to one variant, you must edit the configuration file located at:

    ~/.cc-mirror/<variant>/config/.claude.json

    CC-MIRROR will preserve your manually added MCP servers during updates, while automatically managing provider-managed servers.

  8. Understand Mirror Claude variant structure and environment

    main

    When you create a Mirror Claude variant, cc-mirror sets up an isolated directory structure to ensure configurations (like MCP servers and approvals) do not interfere with your main Claude Code installation.

    Directory Structure

    Variants are stored in ~/.cc-mirror/<variant-name>/:

    • native/: The Claude Code installation.
    • config/: Contains settings.json (minimal env) and .claude.json (MCP servers, approvals).
    • tweakcc/: Contains config.json for the Mirror theme.
    • variant.json: Metadata for the variant.
    • Wrapper: Located in your system's bin directory (e.g., ~/.local/bin on macOS/Linux or ~/.cc-mirror/bin on Windows).

    Environment Variables Set by Mirror

    Mirror Claude automatically injects the following environment variables:

    • CC_MIRROR_SPLASH: 1
    • CC_MIRROR_PROVIDER_LABEL: Mirror Claude
    • CC_MIRROR_SPLASH_STYLE: mirror
    • DISABLE_AUTOUPDATER: 1

  9. How environment variables are built for variants

    main

    cc-mirror constructs the environment for each variant and writes it to ~/.cc-mirror/<variant>/config/settings.json.

    The build process follows this precedence:

    1. Start with the provider's default env.
    2. Apply auth and baseUrl overrides.
    3. Apply model overrides (Primary/Balanced/Fast) if specified.
    4. Apply extra entries provided via --env KEY=VALUE.
    5. Append cc-mirror safety defaults (e.g., DISABLE_UPDATES=1, DISABLE_TELEMETRY=1, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1).

  10. Understand the cc-mirror architecture and directory structure

    main

    cc-mirror creates isolated Claude Code variants. Each variant resides in its own directory under ~/.cc-mirror/<variant>, ensuring that configurations, sessions, and binaries do not interfere with your global Claude Code installation.

    Variant Directory Structure:

    • native/: Contains the native Claude Code binary (claude or claude.exe).
    • config/: Contains settings.json (environment overrides like API keys and model mappings) and .claude.json (API-key approvals and MCP server seeds).
    • tweakcc/: Contains config.json (brand presets and themes) and system-prompts/ (prompt fragment overlays/packs).
    • variant.json: Metadata for the variant.

    Wrappers are installed into a configurable <bin-dir>. The default is ~/.local/bin on macOS/Linux and ~/.cc-mirror/bin on Windows.

  11. Checklist for adding a new provider

    main

    To implement a new provider in cc-mirror, follow these steps:

    1. Define Provider: Add to src/providers/index.ts (configure authMode, requiresModelMapping, etc.).
    2. Create Brand Preset: Add to src/brands/<provider>.ts (set theme colors, thinking verbs, tool denies).
    3. Register Brand: Add to src/brands/index.ts.
    4. UI/Splash: Add wrapper splash style and ASCII art in src/core/wrapper.ts and test with scripts/preview-splash.mjs.
    5. TUI Content: Add education content to src/tui/content/providers.ts.
    6. Documentation: Add help entries to src/cli/help.ts, README tables, and docs/README.md.
    7. Testing:
      • Provider matrix: test/provider-matrix.test.ts
      • E2E creation: test/e2e/creation.test.ts
      • E2E providers list: test/e2e/providers.ts
      • E2E ASCII art: test/e2e/ascii-art.test.ts

  12. Manually apply tweakcc patches to a cc-mirror variant

    main

    If you want to manually enable optional tweakcc features (like swarm mode or session memory) for a specific variant, you can bypass the standard cc-mirror flow using one of these methods.

    Fast Path (Recommended)

    Use the built-in cc-mirror command to trigger the tweak process:

    npx cc-mirror tweak <variant>

    Direct Path (Explicit Target)

    If you need to run tweakcc directly with specific environment variables to target a cc-mirror native installation:

    VARIANT=<variant>
TWEAKCC_CONFIG_DIR="$HOME/.cc-mirror/$VARIANT/tweakcc" \
TWEAKCC_CC_INSTALLATION_PATH="$HOME/.cc-mirror/$VARIANT/native/claude" \
npx tweakcc@4.0.11

    Apply Specific Optional Patches

    To apply a comma-separated list of specific patch IDs:

    VARIANT=<variant>
TWEAKCC_CONFIG_DIR="$HOME/.cc-mirror/$VARIANT/tweakcc" \
TWEAKCC_CC_INSTALLATION_PATH="$HOME/.cc-mirror/$VARIANT/native/claude" \
npx tweakcc@4.0.11 --apply --patches "<patch-a>,<patch-b>"

    Note: Patch names depend on your tweakcc version. Run npx tweakcc@4.0.11 --help to see available IDs.