# claude-mode Switch Claude Code between **Anthropic**, **OpenRouter**, **Z.AI**, a local **LM Studio** or **Ollama** server, and any **custom** Anthropic-compatible endpoint — system-wide, with named per-tier model presets. One write to `~/.claude/settings.json` covers the CLI, the VS Code extension and the desktop app: restart Claude Code and it is on the new provider. API keys stay out of that file. There is a Windows build (PowerShell 5.1, no dependencies) and a POSIX port for Linux and macOS (bash 3.2+ and python3), with a theme-aware terminal menu and an Omarchy bar widget. ``` claude-mode # interactive menu claude-mode status # what the next `claude` launch will use claude-mode anthropic # back to your subscription login claude-mode openrouter # remote gateway, pay per token (preset: default) claude-mode zai # Z.AI GLM coding plan (preset: zai) claude-mode lmstudio # local LM Studio server (preset: lmstudio) claude-mode ollama # local Ollama server (preset: ollama) claude-mode custom # your own Anthropic-compatible URL (preset: custom) ``` ## Install ### Windows (PowerShell 5.1+) ```powershell irm https://git.nebulm.com/smoido/claude-mode/raw/branch/master/install.ps1 | iex ``` Piped in like that there is no checkout, so the installer fetches the repository archive to `%TEMP%` and installs from it. To pass switches (`-Force`, `-SkipKeyPrompt`), download the file and run it; or clone the repository and run `.\install.ps1`. It installs to `~/.claude-mode/` (ACL: you only), puts `claude-mode.cmd` in `~/.local/bin` (already on your User PATH, next to `claude.exe`), and adds a marked block to `~/Documents/WindowsPowerShell/profile.ps1`. If the profile does not load: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`. ### Linux / macOS ```bash curl -fsSL https://git.nebulm.com/smoido/claude-mode/raw/branch/master/linux/install.sh | bash ``` Or clone and run `bash linux/install.sh` (`--skip-key-prompt` to install without storing a key). It installs to `~/.claude-mode/`, symlinks `~/.local/bin/claude-mode`, and adds the `claude` wrapper to `~/.bashrc` / `~/.zshrc` between markers. Keys go to the macOS Keychain, libsecret, `pass`, or a 0600 file that says plainly that it is not encrypted — whichever is available. It runs on the bash 3.2 that macOS ships. Finding running sessions needs `/proc`, so on macOS a switch says it cannot check for them instead of claiming there are none; restart Claude Code yourself after switching there. ### Omarchy bar widget ```bash bash omarchy/install.sh # from a checkout omarchy restart shell # after an upgrade - see below ``` The shell reloads the plugin when its files change, but keeps the old compiled panel alive through that reload, so an upgrade only shows after a shell restart. What the widget does: [docs/bar-widget.md](docs/bar-widget.md). ### Upgrading Re-run the installer. Scripts and `providers.json` are replaced; your presets are kept unless you pass `--force` / `-Force`. The installers never touch `~/.claude/settings.json` — only a switch does, and it backs the file up to `~/.claude-mode/backups/` first (the last 20 are kept). ## First run A shipped preset is a starting point, not a working configuration: no key is stored, and its model ids are whatever was on the machine it was packaged on. So the shipped presets are marked `configured: false`, and a switch to one asks for setup first: ```bash claude-mode setup openrouter # key, then a model per tier from OpenRouter's catalogue claude-mode setup zai # key, then a GLM model per tier claude-mode setup lmstudio # where the server is, whether it wants a key, one model for all tiers claude-mode setup ollama # the same, for Ollama claude-mode setup custom # the endpoint's address and key, then a model per tier ``` In a terminal, a switch that needs setup offers to run it there and then. Presets you build yourself never ask. ## Commands ``` claude-mode interactive menu claude-mode status active mode, preset, model map claude-mode [preset] switch: anthropic, openrouter, zai, lmstudio, ollama, custom claude-mode --yes ...without asking about running sessions claude-mode --force ...even when preflight says it would not work claude-mode setup first-run setup: key, server, models claude-mode preflight [preset] would that switch work? (JSON, no switch) claude-mode doctor check auth, endpoint, model ids, context window, stray env vars claude-mode health rewrite health.json (machine-readable state) claude-mode presets list presets (* = active) claude-mode preset show claude-mode preset new [from] copy a preset (default: `default`) claude-mode preset new --provider

[--blank] copy that provider's default, or start empty claude-mode preset set claude-mode preset all point every tier at one model claude-mode preset url point a preset at another server claude-mode preset auth none|key [ref] claude-mode preset rename claude-mode preset default [provider] [name|--clear] which preset `claude-mode ` picks claude-mode preset rm claude-mode set-key [ref] [key] store a key (hidden prompt; [key] for scripts) claude-mode models [filter] models from the active provider claude-mode models --preset [--refresh|--json] claude-mode sessions [--stop|--restart|--dry-run] running Claude Code sessions; close or reopen them claude-mode repair-session [id] [--apply] make a session resumable after a bad switch claude-mode repair-session --ignore | --unignore | --ignored | --all [--max-age ] claude-mode repair [--all] strip [1m] tags from cached model ids ``` `zai` also answers to `z.ai` and `z-ai`, and `lmstudio` to `lm-studio`. The Windows build covers switching, `status`, `presets`, `preset show|new|set|all|rm`, `set-key`, `models`, `doctor` and `repair`; everything else above is POSIX-only. ## Providers | mode | what it is | key | |---|---|---| | `anthropic` | your Claude subscription login — no gateway at all | your login | | `openrouter` | remote gateway to most vendors' models, pay per token | required | | `zai` | Z.AI's GLM coding plan on its Anthropic endpoint | required | | `lmstudio` | an LM Studio server, local or anywhere on your network | optional | | `ollama` | an Ollama server, local or anywhere on your network | optional | | `custom` | any Anthropic-compatible endpoint: a LiteLLM or Vercel gateway, vLLM, a company proxy | optional | Each provider has its quirks — OpenRouter's guardrail, LM Studio's model ids and chat templates, Ollama's server-side context window — and they are all in [docs/providers.md](docs/providers.md), along with presets, context windows, and how to add a provider of your own (usually one JSON entry, no code). ## Switching while Claude Code is running A switch breaks the sessions already running: their key is re-fetched on a timer and resolves to the new mode while their endpoint stays the old one. So a switch asks first, and `claude-mode sessions --restart` reopens them on the new mode. Worse, a session that takes even one reply from another provider can no longer be resumed on Anthropic — `claude-mode repair-session` rolls it back to its last good message, keeping the cut turns. The whole story: [docs/live-sessions.md](docs/live-sessions.md). ## Troubleshooting - **Run `claude-mode doctor` first.** It checks the key, the helper, the endpoint, every tier's model id, the context window and stray environment variables. - **"your apiKeyHelper script is failing"** — usually a space in your home directory in a `settings.json` written by an old version (re-run the switch), or on Windows a key stored from an elevated shell (`claude-mode set-key ` again, unelevated). Details in [docs/design.md](docs/design.md#when-the-helper-is-failing). - **The session auto-compacts almost at once on a gateway** — the preset's `contextTokens`; see [context windows](docs/providers.md#context-windows-and-early-auto-compaction). - **LM Studio spams "Unable to generate parser for this template"** — the model's chat template; see [LM Studio](docs/providers.md#the-server-error--unable-to-generate-parser-for-this-template-spam). - **Ollama loses track of long conversations** — its server context defaults to 4096 tokens; see [Ollama](docs/providers.md#the-context-window-is-set-on-the-server). - **A switch is refused** — `claude-mode preflight ` says why, and what fixes it; the checks are listed in [docs/design.md](docs/design.md#refusing-a-switch-that-would-not-work). ## Documentation | | | |---|---| | [docs/providers.md](docs/providers.md) | presets, defaults, context windows, every provider, adding one | | [docs/live-sessions.md](docs/live-sessions.md) | what a switch does to running sessions, and repairing them | | [docs/bar-widget.md](docs/bar-widget.md) | the Omarchy bar widget and its panel | | [docs/design.md](docs/design.md) | why it works the way it does | | [docs/architecture.md](docs/architecture.md) | how the pieces fit, and where to change what | | [docs/development.md](docs/development.md) | tests, conventions, releasing | | [CHANGELOG.md](CHANGELOG.md) | what changed, by version | ## Uninstall ```bash claude-mode anthropic # clean settings.json first rm -rf ~/.claude-mode ~/.local/bin/claude-mode # then delete the block between the >>> claude-mode >>> markers in ~/.bashrc / ~/.zshrc ``` On Windows, `claude-mode anthropic`, then remove `~\.claude-mode` and `~\.local\bin\claude-mode.cmd`, and delete the marked block in `profile.ps1`. For the bar widget, remove `~/.config/omarchy/plugins/smoido.claude-mode` and its `{"id": "smoido.claude-mode"}` entry in `~/.config/omarchy/shell.json`. ## Licence [MIT](LICENSE).