KC-Switcher

KC-Switcher is a cross-platform CLI for instantly switching Claude Code between the normal Claude subscription and a local Kiro gateway — with safe, automatic backup and restore of your Claude configuration.

Run it with npx, no install required:

npx kc-switcher use kiro      # switch Claude Code to the local Kiro gateway
npx kc-switcher use claude    # restore your normal Claude subscription

How it works

The tool does not assume Claude Code's private configuration format. It:

1. Discovers likely Claude config/auth locations (~/.claude, ~/.claude.json, %APPDATA%\Claude, …).
2. Captures them once in a timestamped original backup before making any change.
3. Sets or clears the ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY user environment variables.
4. Restores the original backup when you switch back to claude.

Environment-variable changes apply to newly started processes — restart Claude Code after switching.

Commands

npx kc-switcher use <kiro|claude>   # switch active provider
npx kc-switcher status              # show current provider + config status
npx kc-switcher list                # list supported and planned providers
npx kc-switcher doctor              # environment / gateway diagnostics
npx kc-switcher backup              # create a manual backup
npx kc-switcher restore             # restore the most recent backup
npx kc-switcher version             # print version

Global flags

| Flag | Effect | | --- | --- | | --dry-run | Show what would change without writing anything | | --verbose | Enable debug logging | | --no-color | Disable colored output | | --yes, -y | Assume yes for confirmation prompts |

Examples:

npx kc-switcher --dry-run use kiro
npx kc-switcher --yes restore
npx kc-switcher --verbose status

What changes

use kiro

• Verifies http://127.0.0.1:9000 is reachable (aborts with no changes if not).
• Creates the original backup if one does not already exist.
• Sets ANTHROPIC_BASE_URL=http://127.0.0.1:9000 and ANTHROPIC_API_KEY=anything.
• Records the active provider as kiro.

use claude

• Creates a pre-restore safety backup of the current state.
• Restores the original Claude configuration backup.
• Removes ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY.
• Records the active provider as claude.

Backup location

Backups live outside Claude's own config directory:

• Windows: %APPDATA%\kc-switcher\backups
• Linux/macOS: ~/.config/kc-switcher/backups

Each backup contains a manifest.json describing every discovered path, whether it existed, and where it was captured.

Platform notes

• Windows: persistent user environment variables are written to HKCU\Environment and a WM_SETTINGCHANGE broadcast tells new processes to reload them.
• macOS / Linux: the switch updates the current process and prints the export/removal you should add to your shell profile — persistent writes are not automated.

Local development

Requires Node.js >= 16.7 (for fs.cpSync). No runtime dependencies.

npm test           # run the node:test suite
node bin/kc-switcher.js status   # run the CLI from source

Tests use isolated temp home/config directories and never touch your real Claude configuration or the registry.

Extending

Providers are defined as profiles in src/providers.js. kiro and claude are implemented today; additional gateways (Anthropic API, OpenRouter, LiteLLM, Azure OpenAI, Ollama, LM Studio, OpenAI-compatible endpoints) are registered as planned and surface in kc-switcher list. Add a new provider by registering another profile rather than special-casing the CLI.