Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
Claudish Settings Reference
Session: dev-research-claudish-settings-20260316-012741-6e25c3bb Date: 2026-03-16 Status: COMPLETE Sources: Live codebase investigation (cli.ts, config.ts, model-parser.ts, provider-resolver.ts, auto-route.ts, remote-provider-registry.ts, profile-config.ts, routing-rules.ts, local.ts, gemini-oauth.ts, vertex-auth.ts, local-queue.ts)
Executive Summary
Claudish is a proxy tool that wraps Claude Code with support for non-Anthropic AI providers. It intercepts Claude Code's API calls and reroutes them to providers like OpenRouter, Google Gemini, OpenAI, MiniMax, Kimi, GLM, and local models (Ollama, LM Studio, vLLM, MLX). Configuration is layered: CLI flags override environment variables, which override profile settings from config files. The routing syntax uses provider@model[:concurrency] (v4.0+, preferred) or the legacy prefix/model format (still supported, deprecated). Auto-routing selects a provider automatically based on available credentials. The priority chain is configurable via defaultProvider (v7.0.0+). The default chain (when no defaultProvider is set and only OPENROUTER_API_KEY is present) is: OpenCode Zen → provider subscription plan → native API → OpenRouter fallback. When LITELLM_BASE_URL + LITELLM_API_KEY are set without explicit defaultProvider, legacy auto-promotion puts LiteLLM first. Configuration files live at ~/.claudish/config.json (global) and .claudish.json (local/project); local always takes precedence.
1. CLI Flags and Options
All flags recognized by parseArgs() in packages/cli/src/cli.ts.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--model |
-m |
string | none (prompts interactively) | Model to use. Accepts provider@model syntax, legacy prefix/model, or bare model name for auto-detection |
--default-provider |
string | none | Default provider for auto-routing (v7.0.0+). Overrides env var and config file. Valid: built-in provider names or custom endpoint names | |
--config |
path | none | Use this file as the run's ONLY config, replacing both the global and project config. Consumed before parseArgs() — see Config File Override |
|
--accept-served-model |
boolean | false | Allow a reasoning-off that the connection serves with a DIFFERENT model (catalog served_model_changes; e.g. Kimi Code k3: thinking off is served by K2.8 Preview). Without it reasoning stays on and the log says why. Env: CLAUDISH_ACCEPT_SERVED_MODEL=1 (v10.5.0+) |
|
--model-opus |
string | none | Model for Opus role (planning, complex tasks) | |
--model-sonnet |
string | none | Model for Sonnet role (default coding) | |
--model-haiku |
string | none | Model for Haiku role (fast tasks, background) | |
--model-subagent |
string | none | Model for sub-agents (Task tool) | |
--classifier-provider |
string | none (off) | Set to anthropic to route Claude Code's auto-mode permission classifier to native Anthropic while the main loop runs on another provider. See Classifier Passthrough |
|
--classifier-model |
string | claude-sonnet-5 |
Native Claude model the classifier request is rewritten onto. Setting it also enables classifier passthrough | |
--port |
number | random (3000–9000) | Proxy server port | |
--auto-approve |
-y |
boolean | false | Skip permission prompts (passes --dangerously-skip-permissions to Claude Code) |
--no-auto-approve |
boolean | Explicitly enable permission prompts (overrides -y) | ||
--dangerous |
boolean | false | Pass --dangerouslyDisableSandbox to Claude Code |
|
--interactive |
-i |
boolean | auto | Interactive mode (default when no prompt argument given) |
--debug-claudish |
-d |
boolean | false | Enable debug logging to logs/claudish_*.log; also sets --log-level debug unless overridden |
--log-level |
string | "info" |
Log verbosity: debug (full content), info (truncated content), minimal (labels only) |
|
--quiet |
-q |
boolean | auto | Suppress [claudish] log messages (default in single-shot mode) |
--verbose |
-v |
boolean | auto | Show [claudish] messages (default in interactive mode) |
--json |
boolean | false | Output JSON format for tool integration; implies --quiet |
|
--monitor |
boolean | false | Proxy to real Anthropic API and log all traffic (uses Claude Code's native auth) | |
--stdin |
boolean | false | Read prompt from stdin instead of positional arguments | |
--free |
boolean | false | Show only free models in interactive model selector | |
--profile |
string | default profile | Named profile for model mapping | |
--cost-track |
boolean | false | Enable cost tracking; also enables monitor mode | |
--cost-audit |
action | Show cost analysis report and exit | ||
--cost-reset |
action | Reset accumulated cost statistics and exit | ||
--models |
-s / --models-search |
action | List ALL models (from OpenRouter + LiteLLM + local Ollama) or fuzzy-search by query | |
--models-top |
action | List curated recommended models and exit | ||
--models-refresh |
boolean | false | Force refresh of model catalog cache (used with --models or --models-top) |
|
--summarize-tools |
boolean | false | Summarize tool descriptions to reduce prompt size for local/small models | |
--version |
action | Show version and exit | ||
--help |
-h |
action | Show help message and exit | |
--help-ai |
action | Show AI agent usage guide (from AI_AGENT_GUIDE.md) and exit |
||
--init |
action | Install Claudish skill in .claude/skills/claudish-usage/SKILL.md |
||
--mcp |
action | Run as MCP server | ||
--gemini-logout |
action | Clear Gemini OAuth credentials | ||
--kimi-login |
action | Login to Kimi/Moonshot AI via OAuth | ||
--kimi-logout |
action | Clear Kimi OAuth credentials | ||
-- |
separator | Everything after -- passes directly to Claude Code without processing |
Passthrough behavior: Any unrecognized flag is automatically forwarded to Claude Code. If the token immediately following the flag does not start with -, it is consumed as that flag's value. Examples: --agent detective, --effort high, --permission-mode plan.
Positional arguments: Tokens without a leading - are treated as the prompt text and forwarded to Claude Code.
Interactive mode detection: If no positional arguments are given and --stdin is not set, Claudish automatically enters interactive mode (as if --interactive was specified).
--json implies --quiet: When --json is set, config.quiet is forced to true regardless of other flags.
--cost-track enables monitor mode: Setting --cost-track automatically sets config.monitor = true if it is not already set.
2. Subcommands
These are top-level subcommands recognized before flag parsing begins (checked in packages/cli/src/index.ts).
| Command | Description |
|---|---|
claudish init [--local|--global] |
Setup wizard: creates config file and first profile interactively |
claudish profile list [--local|--global] |
List all profiles from one or both scopes |
claudish profile add [--local|--global] |
Add a new profile interactively |
claudish profile remove <name> [--local|--global] |
Remove a named profile |
claudish profile use <name> [--local|--global] |
Set the default profile |
claudish profile show [name] [--local|--global] |
Show profile details (models, timestamps) |
claudish profile edit [name] [--local|--global] |
Edit a profile interactively |
claudish update |
Check for updates and install the latest version (detects npm, bun, brew) |
claudish telemetry on |
Enable telemetry (opt-in) |
claudish telemetry off |
Disable telemetry |
claudish telemetry status |
Show current telemetry consent and configuration |
claudish telemetry reset |
Reset telemetry consent to unasked state |
claudish keychain status |
macOS Keychain backend state and how many keys are stored |
claudish keychain list |
Stored variables, with ••••1234 identification tails (never full values) |
claudish keychain import [opts] |
Copy keys from environment variables and/or 1Password into the Keychain |
claudish keychain set <ENV_VAR> |
Store one key — prompted, or piped on stdin; never passed in argv |
claudish keychain rm <ENV_VAR> |
Remove one key from the Keychain |
claudish keychain enable|disable |
Turn the backend on/off. Moves no secrets; stored items are left untouched |
claudish hooks list [--json] |
Every hook, built-in and user, in the order their actions apply, with severity, scope and load errors |
claudish hooks check <file> [--json] |
Load one hook module on its own and validate it; exit 1 when invalid |
claudish hooks init [dir] |
Write example-hook.ts and claudish-hooks.d.ts into dir (default ~/.claudish/hooks); never overwrites |
claudish hooks corpus [--write] [--json] |
Replay recorded transcripts offline and count plan-mode divergences per model |
claudish hooks telemetry [--enable|--disable] |
Show or set hooks.telemetry.enabled |
claudish subscription models antigravity --raw --json |
Print the account's raw Antigravity fetchAvailableModels response text as one JSON line (schema claudish.subscription-model-list.v1), for the models-index wire-probe runner. macOS only; never prompts. Every exit prints exactly one line: exit 0 on any answer from the backend, 3–7 per failure class, 2 on a usage error, 1 on an internal error. Contract: ai-docs/architecture/providers/antigravity.md § Raw model list for models-index |
macOS Keychain (macOS only). Keys are stored as one generic-password item per environment
variable under the service name claudish, so each is individually visible and deletable in
Keychain Access.app. The Keychain is consulted after config.json and before 1Password —
it is local and needs no desktop-app handshake, but an explicit environment variable or a
config-stored key still wins.
claudish keychain import options:
| Option | Meaning |
|---|---|
--from env|1password|all |
Which source to copy from (default all) |
--only VAR,VAR |
Restrict to these variables |
--dry-run |
Print the plan and stop; writes nothing |
--yes |
Skip the confirmation prompt |
Import prints a plan marking each key new / overwrite / unchanged and asks before writing,
because an overwritten Keychain value cannot be recovered. Environment variables are collected
first and 1Password fills only the gaps, matching runtime precedence.
The config TUI's Providers tab writes to the Keychain by default on macOS: s stores a key
there (the input box names the destination), and x removes the key from both the Keychain and
config.json.
The config TUI's 1Password tab can copy secrets across without leaving the interface:
| Key | Action |
|---|---|
c |
Copy the selected entry into the Keychain — a key becomes one item, a set or an environment becomes one item per variable |
C |
Copy every 1Password entry into the Keychain (the equivalent of claudish keychain import --from 1password) |
Both overwrite an existing Keychain item without a confirmation prompt. That is deliberate:
1Password still holds every value, so a replaced item is a refresh rather than a loss. The status
line reports exactly what happened — 3 new · 1 replaced — and names any variable that could not
be stored.
Scope flags for profile commands:
--local: Target.claudish.jsonin the current working directory--global: Target~/.claudish/config.json- (omit): Prompted interactively; suggests
--localif CWD appears to be a project directory (has.git,package.json,Cargo.toml,go.mod,pyproject.toml, or.claudish.json)
3. Environment Variables
Claudish loads .env from the current working directory at startup, the way dotenv does: a variable already set in your environment is never overwritten, and no $ expansion is applied. It reads that one file. .env.local, .env.<NODE_ENV> and .env.<NODE_ENV>.local are not read: claudish starts Bun with --no-env-file, so Bun's own env-file loading is off.
A .env may set only provider API keys and claudish model settings:
- each provider's key variable and its aliases (§3.3, plus the bundled endpoints' vendor keys), and every
CUSTOM_<NAME>_KEY(§7.5). This list is taken from claudish's provider definitions, so a new provider's key is covered when it ships; ANTHROPIC_API_KEYandVERTEX_LOCATION;CLAUDISH_MODEL,CLAUDISH_MODEL_OPUS,CLAUDISH_MODEL_SONNET,CLAUDISH_MODEL_HAIKUandCLAUDISH_MODEL_SUBAGENT.
Every other variable in the file is ignored, with one stderr line naming them (names only, never values); set those in your shell or an MCP server's env. That includes every *_BASE_URL, OLLAMA_HOST, CLAUDISH_PORT and CLAUDISH_RECOVERY, and a custom endpoint key named anything but CUSTOM_<NAME>_KEY (an apiKey of "${MY_CUSTOM_API_KEY}" reads it from your shell). The working directory is often a checkout you have not reviewed, and several variables choose what code runs or where your data goes: CLAUDE_PATH names the Claude Code executable claudish starts, BUN_OPTIONS and NODE_OPTIONS load a module into every child, a base URL or host would send your existing key to whatever server it names, and GOOGLE_APPLICATION_CREDENTIALS points gcloud at a credentials file (an external_account JSON can name a local file and a token_url gcloud uploads it to), so it is shell-only like the base URLs.
The control variables steer claudish itself: CLAUDISH_CONFIG, CLAUDISH_PANE_CHILD, CLAUDISH_PANE_ENV, CLAUDISH_PANE_CWD, CLAUDISH_HOOK_INBOX, CLAUDISH_HOOK_SESSION and CLAUDISH_BIN. They count only from your shell, an MCP server's env, or the parent claudish that started the process. If Bun was started without --no-env-file (a hand-typed bun <path>/index.js, or bun <path>/claudish.cjs), claudish cannot tell a file's value from yours: it drops every control variable and every name that directory's env files set, then reads the provider API keys and model settings in .env as usual, with one stderr line (see Config File Override).
3.1 Claudish-Specific Variables
| Variable | Purpose | Default |
|---|---|---|
CLAUDISH_DEFAULT_PROVIDER |
Default provider for auto-routing (v7.0.0+); overrides config file defaultProvider |
none |
CLAUDISH_MODEL |
Default model (higher priority than ANTHROPIC_MODEL) |
none |
CLAUDISH_PORT |
Default proxy port | random (3000–9000) |
CLAUDISH_CONTEXT_WINDOW |
Override context window size for local models (integer) | auto-detected |
CLAUDISH_MODEL_OPUS |
Override model for Opus role | none |
CLAUDISH_MODEL_SONNET |
Override model for Sonnet role | none |
CLAUDISH_MODEL_HAIKU |
Override model for Haiku role | none |
CLAUDISH_MODEL_SUBAGENT |
Override model for sub-agents | none |
CLAUDISH_CLASSIFIER_PROVIDER |
Set to anthropic to route the auto-mode permission classifier to native Anthropic (default off). See Classifier Passthrough |
none (off) |
CLAUDISH_CLASSIFIER_MODEL |
Native Claude model the classifier request is rewritten onto; setting it also enables classifier passthrough | claude-sonnet-5 |
CLAUDISH_CLASSIFIER_DEBUG |
Set to 1 to append each incoming request's model/params/system/headers to logs/classifier-capture.jsonl for classifier-detection debugging |
none (off) |
CLAUDISH_SUMMARIZE_TOOLS |
Summarize tool descriptions (true or 1 to enable) |
false |
CLAUDISH_KEYCHAIN_FILE |
Point every macOS Keychain operation at a specific keychain FILE instead of your login keychain. Intended for testing — create one with security create-keychain (it is not added to the search list, so nothing else on the machine is affected) |
none (login keychain) |
CLAUDISH_TELEMETRY |
Override telemetry (0, false, or off to disable) |
from config |
CLAUDISH_ACTIVE_MODEL_NAME |
(Internal) Set by Claudish to display model name in status line | auto |
CLAUDISH_IS_LOCAL |
(Internal) Set to "true" for local models; used by status line to show "LOCAL" instead of cost |
auto |
CLAUDISH_LOCAL_QUEUE_ENABLED |
Enable/disable local model request queue (false or 0 to disable) |
true |
CLAUDISH_LOCAL_MAX_PARALLEL |
Max concurrent local model requests (integer 1–8; values above 8 are capped) | 1 |
CLAUDISH_QWEN_NO_THINK |
Prepend /no_think to system prompt for Qwen local models (set to "1") |
none |
3.2 Claude Code Compatibility Variables
| Variable | Purpose | Fallback for |
|---|---|---|
ANTHROPIC_MODEL |
Claude Code standard model selection | CLAUDISH_MODEL (lower priority) |
ANTHROPIC_SMALL_FAST_MODEL |
Claude Code standard fast model var | — |
ANTHROPIC_DEFAULT_OPUS_MODEL |
Claude Code opus model var | CLAUDISH_MODEL_OPUS (lower priority) |
ANTHROPIC_DEFAULT_SONNET_MODEL |
Claude Code sonnet model var | CLAUDISH_MODEL_SONNET (lower priority) |
ANTHROPIC_DEFAULT_HAIKU_MODEL |
Claude Code haiku model var | CLAUDISH_MODEL_HAIKU (lower priority) |
CLAUDE_CODE_SUBAGENT_MODEL |
Claude Code subagent model var | CLAUDISH_MODEL_SUBAGENT (lower priority) |
ANTHROPIC_API_KEY |
Placeholder to suppress Claude Code API key dialog | (placeholder set by Claudish) |
ANTHROPIC_AUTH_TOKEN |
Placeholder to suppress Claude Code login screen | (placeholder set by Claudish) |
CLAUDE_PATH |
Custom path to Claude Code binary | ~/.claude/local/claude, then global PATH |
Priority for model selection (highest to lowest):
- CLI flag (
--model,--model-opus, etc.) CLAUDISH_MODEL_*environment variablesANTHROPIC_DEFAULT_*/CLAUDE_CODE_SUBAGENT_MODELenvironment variables- Profile models from config (local
.claudish.jsonfirst, then global) - Interactive selector (if no model specified in interactive mode)
3.3 API Keys (Cloud Providers)
| Variable | Provider | Aliases | Where to Get |
|---|---|---|---|
OPENROUTER_API_KEY |
OpenRouter (default backend / universal fallback) | https://openrouter.ai/keys | |
GEMINI_API_KEY |
Google Gemini direct API (g@, google@) |
https://aistudio.google.com/app/apikey | |
OPENAI_API_KEY |
OpenAI direct API (oai@) |
https://platform.openai.com/api-keys | |
MINIMAX_API_KEY |
MiniMax (mm@, mmax@) |
https://platform.minimax.io/user-center/basic-information/interface-key (China platform: https://www.minimaxi.com/, and set MINIMAX_BASE_URL) |
|
MINIMAX_CODING_API_KEY |
MiniMax Coding Plan (mmc@) |
https://platform.minimax.io/ | |
MOONSHOT_API_KEY |
Kimi/Moonshot (kimi@, moon@) |
KIMI_API_KEY |
https://platform.moonshot.cn/ |
KIMI_CODING_API_KEY |
Kimi Coding Plan (kc@); also accepts OAuth via claudish --kimi-login |
https://www.kimi.com/code | |
ZHIPU_API_KEY |
GLM/Zhipu direct API (glm@, zhipu@) |
GLM_API_KEY |
https://open.bigmodel.cn/ |
GLM_CODING_API_KEY |
GLM Coding Plan at Z.AI (gc@) |
ZAI_CODING_API_KEY |
https://z.ai/subscribe |
ZAI_API_KEY |
Z.AI Anthropic-compatible API (zai@) |
https://z.ai/manage-apikey/apikey-list | |
SAKANA_API_KEY |
Sakana Fugu API / token plan (sakana@, fugu@) |
https://console.sakana.ai/get-started | |
SAKANA_CODING_API_KEY |
Sakana Fugu Subscription (sc@) |
SAKANA_API_KEY |
https://console.sakana.ai/get-started |
QWEN_TOKEN_PLAN_API_KEY |
Alibaba Token Plan (qtoken@) — Model Studio subscription, metered in Credits |
(none by design — see the note below) | https://docs.qwencloud.com/token-plan/overview |
QWEN_CODING_PLAN_API_KEY |
Alibaba Coding Plan (qcode@) — Model Studio subscription, metered in requests |
(none by design — see the note below) | https://www.alibabacloud.com/help/en/model-studio/coding-plan |
META_API_KEY |
Meta Model API, metered (meta@). Never signs the muse@ subscription, which uses claudish login muse or the Muse Code CLI's Keychain login |
https://dev.meta.ai | |
DASHSCOPE_API_KEY |
Alibaba PAYG (qpay@) — Model Studio pay-as-you-go, billed per token |
(none by design — see the note below) | https://www.alibabacloud.com/help/en/model-studio/get-api-key |
OLLAMA_API_KEY |
OllamaCloud hosted API (oc@, llama@, lc@) |
https://ollama.com/settings/keys | |
OPENCODE_API_KEY |
OpenCode Zen (zen@) — required |
https://opencode.ai/console (Settings > Service accounts) | |
OPENCODE_GO_API_KEY |
OpenCode Zen Go plan (zgo@, zengo@) — required |
https://opencode.ai/console (Settings > Service accounts) | |
XAI_API_KEY |
xAI / Grok (direct API, detected in model selector) | https://x.ai/ | |
LITELLM_API_KEY |
LiteLLM proxy (ll@, litellm@) |
https://docs.litellm.ai/ | |
POE_API_KEY |
Poe (poe@) |
https://poe.com/ | |
VERTEX_PROJECT |
Vertex AI (v@, vertex@) — GCP project ID; optional, see the note below |
GOOGLE_CLOUD_PROJECT |
GCP Console |
VERTEX_LOCATION |
Vertex AI region | us-central1 |
|
GOOGLE_APPLICATION_CREDENTIALS |
Path to GCP service account JSON file (Vertex OAuth) | GCP Console | |
GOOGLE_CLOUD_PROJECT |
GCP project ID (Vertex AI) | GOOGLE_CLOUD_PROJECT_ID |
Note on Vertex AI (changed 2026-09-21): Vertex has ONE authentication mode — OAuth over a Google Cloud project, using Application Default Credentials (gcloud auth application-default login) or a service account (GOOGLE_APPLICATION_CREDENTIALS). It reaches every Vertex model, partner models (Anthropic Claude, Mistral, etc.) included.
The Express API-key mode (VERTEX_API_KEY) is removed, not deprecated: the variable is no longer read anywhere. Express served Gemini models from the plain Gemini API endpoint, which GEMINI_API_KEY and g@ already do.
You do not have to set VERTEX_PROJECT. Claudish resolves the project in this order, and stops at the first answer:
VERTEX_PROJECT, thenGOOGLE_CLOUD_PROJECTquota_project_idin~/.config/gcloud/application_default_credentials.jsongcloud config get project
If none of them answers, the error says so and names both remedies (VERTEX_PROJECT=… or gcloud config set project …). The project is resolved once per process and never written to disk, so gcloud config set project takes effect on the next run. VERTEX_LOCATION defaults to us-central1.
Note on OpenCode Zen (changed 2026-08-22): OPENCODE_API_KEY is now required for every model on the zen endpoint. Claudish previously sent "Bearer public" when no key was set, on the basis that free-tier models (cost.input === 0) needed no credential. The endpoint answers 401 — Missing API key to that token, and because the fallback also made the provider report Ready without ever issuing a request, the failure only surfaced under a live test. The fallback has been removed; a Zen row with no key now correctly reads "not set".
Note on OpenCode Zen Go (changed 2026-09-02): zgo@ used to accept OPENCODE_API_KEY as an alias, on the documented claim that a key minted for one OpenCode tier is refused by the other with a 401. That claim was measured and is false — a Zen Go key is accepted by the plain Zen endpoint (200), against a bogus-key control that endpoint answers 401. The alias is removed: zgo@ requires OPENCODE_GO_API_KEY. The reason is billing, not access — opencode-zen-go is classified as a flat-rate plan, so a metered Zen key reaching it would have been reported as SUB at $0 while OpenCode billed per token. If you previously ran zgo@ on OPENCODE_API_KEY, set OPENCODE_GO_API_KEY to the key your Lite Plan subscription minted.
Note on Alibaba Model Studio — four products, three isolated silos. Model Studio (also fronted by the QwenCloud console; same service, two consoles) sells four things whose keys and base URLs are, in Alibaba's own words, "completely isolated and must be used in matching pairs". Every silo answers every other silo's key with a near-identical 401, so picking the wrong key is both easy and hard to diagnose. Each silo has its own provider and its own variable, so you can hold all three keys at the same time:
| Product | Billing unit | Prefix | Key | Host |
|---|---|---|---|---|
| Coding Plan | Subscription metered in requests — 6,000 per 5h, 45,000 per week, 90,000 per month ($50/month in Alibaba's published pricing as of 2026-09-17) | qcode@ |
QWEN_CODING_PLAN_API_KEY |
coding-intl.dashscope.aliyuncs.com |
| Token Plan — Individual | Subscription metered in Credits | qtoken@ |
QWEN_TOKEN_PLAN_API_KEY |
token-plan.ap-southeast-1.maas.aliyuncs.com |
| Token Plan — Team | Subscription metered in Credits, one key per seat | qtoken@ |
QWEN_TOKEN_PLAN_API_KEY |
token-plan.ap-southeast-1.maas.aliyuncs.com |
| Credit Packs | Extra Credits with a limited validity window | n/a — a top-up on Token Plan Credits | — | — |
| Pay-as-you-go | Metered per token | qpay@ |
DASHSCOPE_API_KEY |
dashscope-intl.aliyuncs.com |
- One product, one variable, one prefix. Each Alibaba product is named by the variable that opens it and the prefix that selects it, and no product accepts a second spelling of either. A name that identifies a vendor (
QWEN_…) or a category (…CLOUD_PLAN…) is true of more than one of these three products and therefore selects none of them, which is how a subscription key ends up signing a metered request. - No key ever crosses a silo. A Coding Plan key set as the Token Plan's variable is rejected by the Token Plan host, and the reverse holds too;
DASHSCOPE_API_KEYis metered and must never stand in for either subscription, which would cross a plan with a per-token bill. Claudish names the sibling variables in its "no API key" and 401 messages precisely because they are the keys you are most likely to already have exported. - The key format identifies nothing. Alibaba documents
sk-sp-…as the Coding Plan's format; a measured Token Plan key has the same prefix. Claudish never infers a product from a key's bytes, and neither should you. - A bare Qwen name tries the Coding Plan first.
qwen3.*andqwen3-*names route Coding Plan → Token Plan → OpenCode Zen Go → PAYG → OpenRouter, each step only when its credential is present (see §5.3). The Coding Plan serves other vendors' namespaces (glm-4.7,glm-5,kimi-k2.5,MiniMax-M2.5) alongside both Qwen naming styles, and its model-list endpoint is public — it answers in full with no credential at all — so neither the name nor the list can establish that your key covers a model. Alibaba answers an id outside the plan with400 Model not exist(measured on the Token Plan and PAYG hosts), and claudish does not move on to the next candidate after that error. To pin one product, name it:qcode@qwen3-coder-plus,[email protected]. - Credit Packs need no configuration. They change the Credits balance, never the route or the dynamic models catalog.
- Individual vs Team is not modelled. A key's edition is not derivable from anything claudish can read, so nothing in claudish depends on it.
3.4 Custom Endpoints (Remote Providers)
| Variable | Provider | Default |
|---|---|---|
GEMINI_BASE_URL |
Google Gemini API | https://generativelanguage.googleapis.com |
OPENAI_BASE_URL |
OpenAI API (also for Azure-compatible) | https://api.openai.com |
MINIMAX_BASE_URL |
MiniMax API | https://api.minimax.io; set https://api.minimaxi.com for a China-platform key |
MINIMAX_CODING_BASE_URL |
MiniMax Coding Plan endpoint | https://api.minimax.io |
MOONSHOT_BASE_URL |
Kimi/Moonshot API | https://api.moonshot.ai |
KIMI_BASE_URL |
Alias for MOONSHOT_BASE_URL |
|
ZHIPU_BASE_URL |
GLM/Zhipu API | https://open.bigmodel.cn |
GLM_BASE_URL |
Alias for ZHIPU_BASE_URL |
|
ZAI_BASE_URL |
Z.AI API | https://api.z.ai |
QWEN_TOKEN_PLAN_BASE_URL |
Alibaba Token Plan endpoint | https://token-plan.ap-southeast-1.maas.aliyuncs.com |
QWEN_CODING_PLAN_BASE_URL |
Alibaba Coding Plan endpoint | https://coding-intl.dashscope.aliyuncs.com |
DASHSCOPE_BASE_URL |
Alibaba PAYG endpoint; repoint here for a mainland-China account | https://dashscope-intl.aliyuncs.com |
META_BASE_URL |
Meta Model API (meta@) |
https://api.meta.ai |
OLLAMACLOUD_BASE_URL |
OllamaCloud hosted API | https://ollama.com |
OPENCODE_BASE_URL |
OpenCode Zen API (base; /v1/chat/completions appended) |
https://opencode.ai/zen |
LITELLM_BASE_URL |
LiteLLM proxy server URL (required to enable LiteLLM routing) | none |
Note on OPENCODE_BASE_URL: For the Zen Go plan endpoint, Claudish replaces /zen with /zen/go automatically. Setting OPENCODE_BASE_URL=https://opencode.ai/zen is equivalent to the default.
3.5 Local Provider Endpoints
| Variable | Provider | Default |
|---|---|---|
OLLAMA_BASE_URL |
Ollama local server | http://localhost:11434 |
OLLAMA_HOST |
Alias for OLLAMA_BASE_URL |
|
LMSTUDIO_BASE_URL |
LM Studio local server | http://localhost:1234 |
VLLM_BASE_URL |
vLLM local server | http://localhost:8000 |
MLX_BASE_URL |
MLX local server | http://127.0.0.1:8080 |
3.6 Gemini OAuth (Advanced)
| Variable | Purpose | Default |
|---|
These are only needed if you want to use your own Google Cloud OAuth application instead of Claudish's built-in credentials.
4. Configuration Files
4.1 ~/.claudish/config.json (Global Configuration)
{
"version": "1.0.0",
"defaultProfile": "default",
"defaultProvider": "openrouter",
"profiles": {
"default": {
"name": "default",
"description": "Default profile",
"models": {
"opus": "[email protected]",
"sonnet": "google@gemini-3-pro",
"haiku": "[email protected]",
"subagent": "[email protected]"
},
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
},
"telemetry": {
"enabled": false,
"askedAt": "2026-01-01T00:00:00Z",
"promptedVersion": "5.10.0"
},
"routing": {
"kimi-*": ["kc", "kimi", "openrouter"],
"glm-*": ["gc", "glm", "openrouter"],
"*": ["litellm", "openrouter"]
},
"customEndpoints": {
"my-vllm": {
"kind": "simple",
"url": "http://gpu-box:8000",
"format": "openai",
"apiKey": "${VLLM_API_KEY}"
}
}
}
Field descriptions:
version: Config schema version string (currently"1.0.0").defaultProfile: Name of the profile to use when--profileis not specified.defaultProvider(v7.0.0+): Default provider for auto-routing. Accepts built-in provider names ("openrouter","litellm","openai","anthropic","google") or a custom endpoint name. See Section 6.1 for precedence. Absent means use legacy auto-detection.customEndpoints(v7.0.0+): Named map of custom endpoint definitions. See Section 7.5 for schema.keychain(macOS):{ "enabled": true }turns on the macOS Keychain credential backend. It records only that the backend is in USE — the stored variable names are deliberately not mirrored here, because the Keychain enumerates its own contents and a second copy of that list is a second thing that can go stale. Set automatically on the first successful write;claudish keychain disableclears it without removing any stored item. When absent orfalse, claudish performs no Keychain I/O at all.profiles: Map of profile name to profile object. Each profile has:name: Profile identifier (matches the map key).description: Optional human-readable description.models: Model mapping with optional keysopus,sonnet,haiku,subagent. Each value is a full model spec (e.g.,"google@gemini-3-pro"). Absent keys mean no override for that role.createdAt/updatedAt: ISO 8601 timestamps (managed by Claudish).
telemetry: Consent state.enabled: Whether telemetry is on. Default isfalseuntil user explicitly opts in.askedAt: ISO 8601 timestamp of when the user was last prompted. Absent means never prompted.promptedVersion: Claudish version string at time of prompting.
routing: Custom routing rules (see Section 7). Absent means use default auto-routing chain.hooks: The hook system. Read from this file (or the--configoverride) only. Full guide: Hooks."hooks": { "modules": ["~/.claudish/hooks/verify-tests.ts"], // absolute, "~/…", or relative to this file's directory "severity": { "plan-mode/*": "warn", "hook:verify-tests/*": "fix" }, "injection": { "maxConsecutive": 3 }, // 1..20, default 3 "observer": { "enabled": false, "mode": "off" }, // mode: "off" | "suggest" "telemetry": { "enabled": false } // upload consent; default off }modules: Hook modules (.tsor.js), loaded in order. A module that fails to load is skipped with one stderr line; claudish always starts.severity:"[modelGlob:]hookIdGlob"→"off"|"warn"|"fix". Model-scoped keys beat unscoped keys; within each group an exact id beats a glob and a longer glob beats a shorter one. User hook ids arehook:<module file name>/<id>.injection.maxConsecutive: The most hook-caused turns in a row in one session. A turn the caller or a person starts resets the count.observer: The built-inobserver/divergencehook:enabled,mode,model,timeoutMs,watchTools.telemetry.enabled: Consent to upload behaviour telemetry. Separate from the top-leveltelemetryconsent. Local journaling (~/.claudish/behavior-journal.jsonl) is always on.
An invalid
hooksblock prints one[claudish] hooks config:line per problem and runs with built-in hooks only.behavior(removed): The earlier hook config block. claudish no longer reads it. When the global config still has one, claudish prints once per process what each key moved to, and ignores it otherwise:[claudish] the "behavior" config block is no longer read. Move it to "hooks": [claudish] behavior.rules → hooks.severityThe moves are
behavior.rules→hooks.severity;behavior.hooks→hooks.modules(each module rewritten toapiVersion: 1);behavior.observer→hooks.observer;behavior.telemetry→hooks.telemetry(consent is not carried over);behavior.preset→ removed. The block stays in the file, and saves keep it, until you delete it.claudish hooks listreports whether it is still there.
4.2 .claudish.json (Local/Project Configuration)
Same schema as ~/.claudish/config.json. Placed in the project root directory (wherever Claudish is run from).
Resolution order:
- Profile lookup: local
.claudish.jsonprofiles checked first, then global~/.claudish/config.json. - Default profile: local
defaultProfiletakes precedence if the local config exists and specifies one. - Custom routing rules: local
routingkey entirely replaces global routing rules (no merge). - Local config does not include
telemetry(consent is global only). - A
hookskey in.claudish.jsonis ignored, with one stderr line:[claudish] hooks in <path> ignored: hooks are read from the global config only. A project file is controlled by the repository, and claudish does not run code it names.
Note: The default profile in the local config is looked up first in local profiles, then in global profiles. A local config can reference global profiles by name.
4.3 ~/.claudish/ Directory Contents
| File | Purpose | Auto-updated |
|---|---|---|
config.json |
Global config: profiles, telemetry, routing | Manual (via claudish profile commands) |
all-models.json |
Cached full model catalog from OpenRouter | Every 2 days, or on --models-refresh |
litellm-models-{hash}.json |
Cached LiteLLM model list per server (hash = SHA-256 of LITELLM_BASE_URL) |
On each LiteLLM model fetch |
kimi-oauth.json |
Kimi OAuth credentials (access + refresh tokens) | On claudish --kimi-login |
meta-muse-oauth.json |
claudish's own Muse Code login (0600) | On claudish login muse; deleted by claudish logout muse |
meta-muse-borrowed.json |
claudish's copy of the Muse Code CLI's login, so team slots and MCP sessions can sign without a Keychain dialog (0600) |
After an interactive launch reads the Keychain and Meta confirms the subscription; deleted by claudish logout muse |
muse-keychain-read.lock |
Held while one process waits on the Muse Keychain dialog, so other processes wait instead of opening a second one | Removed when the read ends |
logs/ |
Debug log files (created when --debug-claudish is used) |
Per session |
hooks/ |
Default directory of claudish hooks init |
On claudish hooks init |
behavior-journal.jsonl |
Local journal of every hook decision | On every hook decision |
behavior-outbox.jsonl |
Behaviour-telemetry reports waiting for upload (only with hooks.telemetry.enabled) |
At exit; drained by a later run |
behavior-divergences.jsonl |
Verdicts of the built-in observer | When the observer is on |
4.4 Config File Override (--config)
--config <file> (env: CLAUDISH_CONFIG) makes that file the only config for the run. It
replaces both ~/.claudish/config.json and the project .claudish.json — the project file is
not merged back in.
claudish --config ./qa-config.json --model [email protected] "task"
CLAUDISH_CONFIG=/abs/qa-config.json claudish --model [email protected] "task"
| Detail | Behavior |
|---|---|
| Precedence | The --config flag wins over CLAUDISH_CONFIG; a dangling --config (or one followed by another flag) is a usage error, not a silent fallback |
| Flag visibility | Consumed and stripped before parseArgs(), so the child claude process never sees it |
| Child processes | Re-exported as an absolute CLAUDISH_CONFIG and set explicitly in the environment of every claudish child that team and MCP sessions spawn, so each child reads the same file, whatever the child's working directory holds |
| Writes | claudish config saves target the override file — the machine config is never mutated with override-derived data |
| Env vars | Still resolve first: a shell env var or .env entry beats the override file's apiKeys |
.env |
CLAUDISH_CONFIG must come from the shell, an MCP server's env, or a parent claudish: it names the hook modules claudish imports, the endpoints your keys are sent to, and the 1Password sources it reads. No env file in the working directory can set it. claudish starts Bun with --no-env-file, and its own .env load sets provider API keys and model settings only, ignoring CLAUDISH_CONFIG with one stderr line. If Bun loaded the directory's env files anyway (started without --no-env-file), CLAUDISH_CONFIG is ignored for the whole run, with one stderr line; use --config then |
| Scope | Config only. OAuth credential files (kimi-oauth.json, gemini-oauth.json, …) stay machine-level |
It is substitution, not "1Password off". The override does not suppress 1Password — it changes
which file the 1Password sources are read from. An override file that names no op:// source has
no 1Password sources at all, so the lazy SDK gate never opens and no auth prompt appears. An
override file that does name an op:// ref resolves it normally.
The same rule applies to the macOS Keychain: the override changes which file the keychain.enabled
flag is read from. An override file without that flag performs no Keychain I/O; one with it reads
the same machine Keychain as usual. (To redirect the Keychain itself — for testing — use
CLAUDISH_KEYCHAIN_FILE, which is a separate axis from --config.)
5. Provider Routing Syntax
5.1 Current Syntax (v4.0+): provider@model[:concurrency]
The preferred syntax. The @ separator unambiguously identifies the provider.
google@gemini-3-pro # Direct Google Gemini API
[email protected] # Direct OpenAI API
openrouter@deepseek/deepseek-r1 # Explicit OpenRouter with vendor-prefixed model
[email protected] # Local Ollama, sequential (default)
[email protected]:3 # Local Ollama, allow up to 3 concurrent requests
[email protected]:0 # Local Ollama, no concurrency limit (bypass queue)
ll@my-model # LiteLLM proxy with auto catalog resolution
Provider part is case-insensitive. Shortcuts are resolved to canonical provider names.
Request mode and speed markers (v10.5.0+). A model spec may end in +pro and/or
#<speed> (fast, priority, flex, ultrafast, standard):
cx@gpt-6-sol+pro # reasoning mode pro
oai@gpt-6-sol#fast # fast speed tier (sent as the connection's native value, e.g. service_tier=priority)
oai@gpt-6-sol+pro#flex # both, in either order
A marker is only a REQUEST. Each catalog connection publishes which modes and speeds it offers
(claudish --probe <model> prints them); a value the connection does not offer is refused with
the list it does offer, never silently dropped or guessed. A faster tier can bill at a higher
rate. The markers need a catalog connection (or a custom endpoint); they are refused elsewhere.
-pro/-fast are NOT markers: gpt-6-sol-pro and kimi-k3-fast are separate models.
5.2 Provider Shortcuts
Remote Providers
| Shortcut(s) | Canonical Provider | Notes |
|---|---|---|
g, gemini |
google |
Direct Google Gemini API (GEMINI_API_KEY) |
oai |
openai |
Direct OpenAI API (OPENAI_API_KEY) |
or, openrouter |
openrouter |
OpenRouter (OPENROUTER_API_KEY) |
mm, mmax |
minimax |
MiniMax direct API (MINIMAX_API_KEY) |
mmc |
minimax-coding |
MiniMax Coding Plan (MINIMAX_CODING_API_KEY) |
kimi, moon, moonshot |
kimi |
Kimi/Moonshot API (MOONSHOT_API_KEY or KIMI_API_KEY) |
kc |
kimi-coding |
Kimi Coding Plan (KIMI_CODING_API_KEY or OAuth) |
glm, zhipu |
glm |
GLM/Zhipu direct API (ZHIPU_API_KEY or GLM_API_KEY) |
gc |
glm-coding |
GLM Coding Plan at Z.AI (GLM_CODING_API_KEY or ZAI_CODING_API_KEY) |
zai |
zai |
Z.AI Anthropic-compatible API (ZAI_API_KEY) |
sakana, fugu |
sakana |
Sakana Fugu API / token plan (SAKANA_API_KEY) |
sc |
sakana-coding |
Sakana Fugu Subscription (SAKANA_CODING_API_KEY or SAKANA_API_KEY) |
qtoken |
qwen-token-plan |
Alibaba Token Plan — Model Studio subscription, Credits (QWEN_TOKEN_PLAN_API_KEY) |
qcode |
qwen-coding |
Alibaba Coding Plan — Model Studio subscription, requests (QWEN_CODING_PLAN_API_KEY) |
qpay |
qwen-payg |
Alibaba PAYG — Model Studio pay-as-you-go, per token (DASHSCOPE_API_KEY) |
oc, llama, lc |
ollamacloud |
OllamaCloud hosted API (OLLAMA_API_KEY). meta is no longer an OllamaCloud shortcut |
meta |
meta |
Meta Model API, metered (META_API_KEY) |
muse |
meta-muse-code |
Muse Code subscription (claudish login muse, or the Muse Code CLI's Keychain login); see Muse Code |
zen |
opencode-zen |
OpenCode Zen (OPENCODE_API_KEY required) |
zengo, zgo |
opencode-zen-go |
OpenCode Zen Go subscription plan (OPENCODE_GO_API_KEY required) |
v, vertex |
vertex |
Vertex AI — Application Default Credentials (VERTEX_PROJECT optional) |
mistral |
mistralai |
Direct Mistral API (MISTRAL_API_KEY) |
ag, antigravity |
antigravity |
Gemini via your Antigravity subscription (claudish login antigravity) |
go |
antigravity |
deprecated alias — Gemini Code Assist was retired by Google |
litellm, ll |
litellm |
LiteLLM proxy (LITELLM_BASE_URL + LITELLM_API_KEY) |
poe |
poe |
Poe API (POE_API_KEY) |
Local Providers (no API key required)
| Shortcut(s) | Provider | Default Endpoint |
|---|---|---|
ollama |
Ollama | http://localhost:11434 |
lms, lmstudio, mlstudio |
LM Studio | http://localhost:1234 |
vllm |
vLLM | http://localhost:8000 |
mlx |
MLX | http://127.0.0.1:8080 |
5.3 Native Auto-Detection (no provider prefix)
When no provider@ prefix is given, Claudish detects the provider from the model name pattern. Resolution is by the first matching pattern:
| Pattern | Routes To | Notes |
|---|---|---|
google/* or gemini-* |
Google Gemini | |
openai/* or gpt-* or o1-* or o3-* or chatgpt-* |
OpenAI | |
minimax/* or minimax-* or abab-* |
MiniMax | |
kimi-for-coding (exact) |
Kimi Coding Plan | Must match exactly; checked before kimi-* |
moonshot/* or moonshot-* or kimi-* |
Kimi | |
zhipu/* or glm-* or chatglm-* |
GLM | |
z-ai/* or zai/* |
Z.AI | |
fugu* or sakana/* |
Sakana Fugu | |
ollamacloud/* or meta-llama/* or llama-* or llama3* |
OllamaCloud | |
qwen3.* (dotted Model Studio names, e.g. qwen3.7-plus) |
Alibaba Token Plan (qtoken@) |
Bare-name routing chain: Alibaba Coding Plan (qcode@), Alibaba Token Plan (qtoken@), OpenCode Zen Go, Alibaba PAYG (qpay@), then OpenRouter — each step only if that credential is present |
qwen3-* (hyphenated, e.g. qwen3-coder-plus) |
Auto-routed (no direct API) | Same routing chain as qwen3.* |
qwen* (everything else) |
Auto-routed (no direct API) | Falls to OpenRouter or LiteLLM |
poe:* |
Poe | Literal poe: prefix |
anthropic/* or claude-* |
Native Anthropic | Claude Code's own auth, no proxy |
vendor/model (unknown vendor) |
Error | Must use explicit openrouter@vendor/model |
bare name (no /) |
Native Anthropic | Treated as Claude model; no proxy |
5.4 Legacy Prefix Syntax (deprecated, still supported)
The old prefix/model format works but emits a deprecation warning suggesting the @ syntax.
| Legacy Prefix | Provider | New Equivalent |
|---|---|---|
g/ |
Google Gemini | g@ |
gemini/ |
Google Gemini | gemini@ |
ag/, antigravity/ |
Antigravity (Gemini subscription) | ag@ |
oai/ |
OpenAI | oai@ |
or/ |
OpenRouter | or@ |
mmax/, mm/ |
MiniMax | mm@ |
mmc/ |
MiniMax Coding | mmc@ |
kimi/, moonshot/ |
Kimi | kimi@ |
kc/ |
Kimi Coding | kc@ |
glm/, zhipu/ |
GLM | glm@ |
gc/ |
GLM Coding | gc@ |
zai/ |
Z.AI | zai@ |
sakana/, fugu/ |
Sakana Fugu | sakana@, fugu@ |
sc/ |
Sakana Subscription | sc@ |
oc/ |
OllamaCloud | oc@ |
zen/ |
OpenCode Zen | zen@ |
zengo/, zgo/ |
OpenCode Zen Go | zengo@ |
v/, vertex/ |
Vertex AI | v@ |
litellm/, ll/ |
LiteLLM | ll@ |
ollama/, ollama: |
Ollama (local) | ollama@ |
lmstudio/, lmstudio:, mlstudio/, mlstudio: |
LM Studio (local) | lms@ |
vllm/, vllm: |
vLLM (local) | vllm@ |
mlx/, mlx: |
MLX (local) | mlx@ |
5.5 Custom URL Syntax
A full URL is accepted directly as a model spec and treated as a local custom endpoint (no API key required):
http://localhost:11434/llama3.2
http://192.168.1.100:8000/mistral
https://localhost:8080/model
6. Auto-Routing Priority Chain
When a model name has no explicit provider prefix and does not match a native pattern that maps to a provider with credentials, Claudish builds a fallback chain (implemented in auto-route.ts / getFallbackChain()).
6.1 Default Provider (v7.0.0+)
The fallback chain is configurable via the defaultProvider setting. Set it in any of these locations:
| Method | Example |
|---|---|
| Config file | "defaultProvider": "litellm" in ~/.claudish/config.json |
| Env var | CLAUDISH_DEFAULT_PROVIDER=openrouter |
| CLI flag | claudish --default-provider google "task" |
Precedence (highest to lowest):
- CLI flag
--default-provider CLAUDISH_DEFAULT_PROVIDERenv vardefaultProviderin config file- Legacy LITELLM auto-promotion (if
LITELLM_BASE_URL+LITELLM_API_KEYset without explicitdefaultProvider) OPENROUTER_API_KEYpresent → OpenRouter- Hardcoded
"openrouter"
Valid values: any built-in provider name ("openrouter", "litellm", "openai", "anthropic", "google") or a custom endpoint name from customEndpoints.
6.2 Default chain (no defaultProvider set)
When defaultProvider is absent and only OPENROUTER_API_KEY is present:
- OpenCode Zen — if
OPENCODE_API_KEYis set. - Provider subscription/coding plan — if the native provider has a subscription alternative and credentials exist:
kimi→ Kimi Coding Plan (kc@kimi-for-coding) ifKIMI_CODING_API_KEYor OAuth present.minimax→ MiniMax Coding Plan (mmc@) ifMINIMAX_CODING_API_KEYpresent.glm→ GLM Coding Plan at Z.AI (gc@) ifGLM_CODING_API_KEYorZAI_CODING_API_KEYpresent.gemini-*→antigravity(subscription) →google(direct API) →openrouter.
- Native provider API — if the detected native provider has an API key or OAuth credentials.
- OpenRouter — if
OPENROUTER_API_KEYis set (universal fallback).
6.3 Legacy LiteLLM auto-promotion
When LITELLM_BASE_URL and LITELLM_API_KEY are set but defaultProvider is absent, LiteLLM is added to the chain first (before OpenCode Zen). Claudish emits a one-shot stderr hint recommending you set defaultProvider: "litellm" explicitly. This preserves backward compatibility with pre-v7.0.0 behavior.
If none of the chain entries have valid credentials, Claudish returns an error with instructions on how to authenticate.
7. Custom Routing Rules
Custom routing rules are defined in the routing key of config.json or .claudish.json. Local rules entirely replace global rules (no merge).
{
"routing": {
"kimi-for-coding": ["kc", "kimi", "or"],
"kimi-*": ["kimi", "or@moonshot/kimi-k2"],
"glm-*": ["gc", "glm"],
"*": ["litellm", "openrouter"]
}
}
Pattern Matching (priority order)
- Exact match — e.g.,
"kimi-for-coding": checked first. - Glob patterns — single
*wildcard, e.g.,"kimi-*". Multiple patterns are sorted longest-first (most specific wins). - Catch-all —
"*": matches any model not matched above.
Entry Format
Each entry in the routing chain array is a string. Format options:
"provider"— Use the original model name on the specified provider (e.g.,"kimi"useskimi@{originalModelName})."provider@model"— Use a specific model on the provider (e.g.,"or@moonshot/kimi-k2"uses OpenRouter with the given model ID).
Provider shortcuts (same as @ syntax) are resolved in entries. LiteLLM entries automatically use the model catalog resolver to find the vendor-prefixed model name.
Catch-All Synthesis from defaultProvider (v7.0.0+)
When defaultProvider is set and no explicit routing["*"] catch-all exists in the config, Claudish synthesizes routing["*"] = [<defaultProvider>] at config load time. An explicit routing["*"] always takes precedence over the synthesized one.
{
"defaultProvider": "litellm",
"routing": {
"kimi-*": ["kc", "kimi", "or"]
}
}
The above is equivalent to:
{
"routing": {
"kimi-*": ["kc", "kimi", "or"],
"*": ["litellm"]
}
}
Validation
Claudish warns at load time if:
- A pattern has multiple
*wildcards (only single*is supported). - A rule's entry list is empty (the pattern would have no fallback).
7.5 Custom Endpoints (v7.0.0+)
Define named custom endpoints in ~/.claudish/config.json (or .claudish.json) under the customEndpoints key. Each endpoint becomes a provider prefix usable with @ syntax.
Simple endpoint
For OpenAI- or Anthropic-compatible servers:
{
"customEndpoints": {
"my-vllm": {
"kind": "simple",
"url": "http://gpu-box:8000",
"format": "openai",
"apiKey": "${VLLM_API_KEY}",
"modelPrefix": "my-org/",
"models": ["llama3.1-70b", "qwen2.5-72b"]
}
}
}
| Field | Type | Required | Description |
|---|---|---|---|
kind |
"simple" |
yes | Discriminator |
url |
string | yes | Base URL of the server |
format |
"openai" or "anthropic" |
yes | Wire format |
apiKey |
string | yes, unless authScheme: "none" |
API key; supports ${VAR} env expansion. Must be omitted under authScheme: "none" |
authScheme |
"bearer", "x-api-key" or "none" |
no | Auth header scheme (default: bearer) |
modelPrefix |
string | no | Prepended to model name before sending to API |
models |
string[] | no | Restrict to listed models; omit to allow any |
wire |
object | no | How requests are built — see Declaring the wire below |
Usage: claudish --model [email protected] "task"
No-credential endpoints: for a local router or a server on a trusted network, set
authScheme: "none" and omit apiKey. claudish then sends no auth header at all:
{
"customEndpoints": {
"localrouter": {
"kind": "simple",
"url": "http://127.0.0.1:8402/v1",
"format": "openai",
"authScheme": "none"
}
}
}
A placeholder such as "apiKey": "none" is not equivalent — it is a literal key and goes
out as Authorization: Bearer none, which some gateways reject. Declared headers are still
sent under authScheme: "none", so a gateway whose auth lives in a custom header works.
Complex endpoint
Full control over transport, auth, headers, and stream format:
{
"customEndpoints": {
"corp-proxy": {
"kind": "complex",
"displayName": "Corporate LLM Proxy",
"transport": "openai",
"baseUrl": "https://llm.corp.internal",
"apiPath": "/api/v2/chat/completions",
"apiKey": "${CORP_LLM_KEY}",
"authScheme": "x-api-key",
"headers": { "X-Team": "platform" },
"streamFormat": "openai-sse",
"modelPrefix": "",
"models": ["gpt-4o", "claude-sonnet"]
}
}
}
| Field | Type | Required | Description |
|---|---|---|---|
kind |
"complex" |
yes | Discriminator |
displayName |
string | no | Human-readable name (shown in logs) |
transport |
string | yes | Transport type (e.g., "openai", "anthropic") |
baseUrl |
string | yes | Server base URL |
apiPath |
string | no | Custom API path (overrides default for transport) |
apiKey |
string | yes, unless authScheme: "none" |
API key; supports ${VAR} env expansion. Must be omitted under authScheme: "none" |
authScheme |
"bearer", "x-api-key" or "none" |
no | Auth header scheme (default: bearer). "none" sends no auth header at all — for a local router or a trusted-network server; do not fake it with a placeholder key, which goes out as a real Authorization: Bearer <placeholder>. Lowercase enum — a capitalized "X-Api-Key" fails validation and the entire entry is skipped |
headers |
object | no | Additional HTTP headers |
streamFormat |
string | no | Stream parser override (e.g., "openai-sse", "anthropic-sse") |
modelPrefix |
string | no | Prepended to model name |
models |
string[] | no | Restrict to listed models |
wire |
object | no | How requests are built — see Declaring the wire below |
Declaring the wire (v10.5.0+)
claudish never chooses a request's output-limit field or reasoning parameters from the model
name. A catalog provider gets them from the cloud models catalog; a custom endpoint gets them
from its wire block, or from these documented defaults:
| Field | Default | Meaning |
|---|---|---|
api |
the transport's API | "chat-completions", "responses" (openai transport only) or "anthropic-messages" |
tokenParam |
max_tokens (max_output_tokens on Responses) |
The output-limit field; "none" sends no limit |
reasoning |
nothing sent | effort: { path, values?, default? }, enable: [{path, value}], disable: [{path, value}] |
Paths are RFC 6901 pointers into the request body. effort.values maps claudish's effort
names (none, minimal, low, medium, high, xhigh, max) to the endpoint's own values;
when omitted, the names are sent as they are. A requested effort the endpoint does not list is
clamped to the nearest one it does. Example for a vLLM server running a Qwen thinking model:
"wire": {
"tokenParam": "max_tokens",
"reasoning": {
"enable": [{ "path": "/chat_template_kwargs/enable_thinking", "value": true }],
"disable": [{ "path": "/chat_template_kwargs/enable_thinking", "value": false }]
}
}
Before v10.5.0 claudish picked these from the model name (a Qwen name got enable_thinking,
a gpt-5 name got max_completion_tokens); such an endpoint now needs the block above, or
--model-params, to keep that behaviour.
Environment variable expansion
The apiKey field supports ${VAR_NAME} syntax. Claudish expands it from process.env at startup. This avoids hardcoding secrets in config files:
"apiKey": "${MY_CUSTOM_API_KEY}"
Validation
Claudish validates all customEndpoints entries with Zod at proxy startup. Invalid entries:
- Emit a warning to stderr with the validation error
- Are skipped (not registered)
- Do not prevent the proxy from starting
Runtime registration
Each valid custom endpoint calls registerRuntimeProvider() (injects into the provider resolver) and registerRuntimeProfile() (injects into the transport layer). The endpoint name becomes a valid provider shortcut immediately.
Predefined endpoints
25 vendors ship inside the package as a bundled catalog (providers/predefined-catalog.ts). Each row compiles into exactly the complex customEndpoints entry documented above and travels the same registration path — there is no separate transport or provider table.
A bundled row activates only when its key is already present locally — the vendor's own env var (e.g. GROQ_API_KEY), one of its aliases, CUSTOM_<NAME>_KEY, config.apiKeys, or (on macOS, when the backend is enabled) the Keychain. The check is synchronous. The Keychain qualifies because presence for every vendor is answered by a single enumeration rather than a lookup per vendor; 1Password cannot be reached synchronously at all, so a key stored only behind an op:// reference will not make its vendor appear — use enable below, export the variable, or copy it into the Keychain with claudish keychain import.
{
"predefinedEndpoints": {
"enabled": true,
"enable": ["groq", "cerebras"],
"disable": ["perplexity"]
}
}
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
false turns the whole catalog off |
enable |
string[] | [] |
Register these rows regardless of whether a key is present |
disable |
string[] | [] |
Never register these rows (beats enable) |
Env kill switch: CLAUDISH_NO_PREDEFINED_ENDPOINTS=1.
Other behaviours worth knowing:
- A
customEndpointsentry of the same name REPLACES the bundled row entirely — no merge. Your entry getsCUSTOM_<NAME>_KEY, so it does not inherit the vendor's conventional variable; add"apiKey": "${GROQ_API_KEY}"to keep using it. Claudish warns when that variable is set and would now be ignored. - A row's base URL can be overridden, when it declares one (e.g.
TUNING_ENGINES_BASE_URLontuningengines), fromconfig.endpoints["TUNING_ENGINES_BASE_URL"]— whatclaudish configand the Providers tab's URL editor write — or from the environment variable of the same name. Config wins over environment, matching theapiKeysrule. - A malformed base-URL override skips the row rather than falling back to the bundled public URL, whichever source it came from. Silently redirecting a typo to a vendor's public host would leak the traffic a self-hosted gateway exists to contain. An unexpanded
${VAR}placeholder is treated as unset, not as malformed. - Turning a row off takes effect on the next start. Runtime registration cannot be undone within a live process, so a row disabled mid-session keeps answering until claudish restarts. Claudish prints a warning naming the row and the reason rather than leaving that silent.
- No model list ships with a row. Catalog vendors get a free-text model prompt in the picker; model metadata comes from models-index or is absent.
- Nothing claudish ships puts a bundled row in a bare-name routing chain. No row declares native model patterns or a legacy prefix, and none is bound to a route in the cloud models catalog, so a row is reachable only as
vendor@model— an ambient key can add a picker row but cannot silently receive a request. Routing proposes a provider only when a catalog connection resolves to it, so an unbound row cannot be proposed for any model. (togetherandfireworksare bound on purpose: they are gateways the catalog maps, and activating one is you naming it.) The other exception is also your own doing: the fallback is appended to every bare chain, so setting"defaultProvider": "groq"does route bare names there. - An invalid
predefinedEndpointsblock warns once and is treated as absent, never as "off". - Evidence: every shipped row is probe-verified — its configured path was confirmed to reach the vendor's own auth layer, and a deliberately bogus sibling path was confirmed to answer differently. No row is live-verified; that establishes the route, not the vendor's streaming dialect on a successful turn.
8. Model Mapping Priority
For each role slot (opus, sonnet, haiku, subagent), resolution from highest to lowest priority:
- CLI flag:
--model-opus,--model-sonnet,--model-haiku,--model-subagent CLAUDISH_MODEL_OPUS,CLAUDISH_MODEL_SONNET,CLAUDISH_MODEL_HAIKU,CLAUDISH_MODEL_SUBAGENTANTHROPIC_DEFAULT_OPUS_MODEL,ANTHROPIC_DEFAULT_SONNET_MODEL,ANTHROPIC_DEFAULT_HAIKU_MODEL,CLAUDE_CODE_SUBAGENT_MODEL- Profile
modelsfields from active profile (local.claudish.jsonfirst, then global~/.claudish/config.json) - No mapping set: Claude Code uses its own internal defaults for that role
The primary model (--model / CLAUDISH_MODEL / ANTHROPIC_MODEL) is separate from role mappings and determines what provider/model handles the main conversation. Role mappings tell Claude Code which models to use internally for different task types.
9. Local Model Support
Claudish provides specialized support for local inference servers with these behaviors:
Context Window
- Detected automatically via Ollama's
/api/showendpoint or LM Studio's/v1/modelsendpoint. - Override with
CLAUDISH_CONTEXT_WINDOW=<integer>. - For Ollama, Claudish explicitly sets
options.num_ctxto at least 32768 to prevent Ollama's default 2048-token silent truncation.
Request Queue
The LocalModelQueue (in handlers/shared/local-queue.ts) serializes requests to prevent GPU out-of-memory errors:
- Default: sequential (1 at a time), controlled by
CLAUDISH_LOCAL_MAX_PARALLEL. - Range: 1–8 (values above 8 are capped at 8).
- Disable entirely:
CLAUDISH_LOCAL_QUEUE_ENABLED=false. - Per-model override via concurrency suffix:
[email protected]:3allows 3 concurrent requests for that model spec. ollama@model:0means no concurrency limit (bypasses the queue).
Timeouts
Local provider requests use extended timeouts (10 minutes for headers + body) to accommodate slow local inference. Default undici headersTimeout of 30s is too short.
Tool Description Summarization
For small local models with limited context, --summarize-tools (or CLAUDISH_SUMMARIZE_TOOLS=1) compresses Claude Code's tool descriptions to reduce prompt token usage.
Qwen No-Think Mode
For local Qwen models, setting CLAUDISH_QWEN_NO_THINK=1 prepends /no_think to the system prompt to disable the model's chain-of-thought reasoning mode, reducing latency.
10. Cache and Data Files
| Path | Purpose | Auto-update Trigger |
|---|---|---|
~/.claudish/config.json |
Global settings, profiles, telemetry, routing | Profile/telemetry commands |
~/.claudish/all-models.json |
Full OpenRouter model catalog | Every 2 days; or --models-refresh |
~/.claudish/recommended-models-cache-v2.json |
Recommended list projection (--models-top, MCP list_models) |
After 24 h; or --models-refresh |
~/.claudish/litellm-models-{hash}.json |
LiteLLM model list (one file per unique LITELLM_BASE_URL) |
On each LiteLLM model list fetch |
~/.claudish/kimi-oauth.json |
Kimi OAuth access + refresh tokens | claudish --kimi-login |
.claudish.json |
Local/project config | Profile commands with --local |
.env |
Provider API keys and claudish model settings (loaded at startup; every other variable is ignored, see §3) | Manual |
Cache files can be force-refreshed with claudish --models --models-refresh or claudish --models-top --models-refresh. The --models-refresh flag deletes all-models.json, pricing-cache.json, recommended-models-cache-v2.json, and all litellm-models-*.json files before fetching fresh data.
11. MCP (Model Context Protocol) Server Mode
Running claudish --mcp starts Claudish as an MCP server. In this mode, Claudish exposes itself as a tool provider to MCP-compatible clients rather than launching Claude Code.
12. Vendor Prefix Auto-Resolution (ModelCatalogResolver)
When routing through aggregators like OpenRouter or LiteLLM, models require vendor-prefixed names (e.g., qwen/qwen3-coder-next) that users should not need to know. The ModelCatalogResolver interface in providers/model-catalog-resolver.ts automatically finds the correct prefix.
How it works:
- User specifies bare model name (e.g.,
or@qwen3-coder-next). - Resolver searches the provider's cached model catalog for an exact suffix match.
- If found, uses the vendor-prefixed ID (e.g.,
qwen/qwen3-coder-next). - If not found in cache, falls back to static map (
OPENROUTER_VENDOR_MAP) for cold starts.
Rules:
- Exact match only; no fuzzy or normalized matching.
- Dynamic catalogs (from provider APIs) are primary; static map is cold-start fallback only.
- Resolution is synchronous (
resolveModelNameSync()) using in-memory cache +readFileSync.
Current resolvers:
- OpenRouter: Searches
_cachedOpenRouterModels+all-models.jsonby exact suffix. - LiteLLM: Searches
litellm-models-{hash}.jsonby exact match and prefix-stripping. - Static fallback:
OPENROUTER_VENDOR_MAPfor OpenRouter when no cache exists.
13. Limitations
This reference does NOT cover:
- Claude Code flags: The full list of flags that can be passed through to Claude Code (use
claude --help). Claudish forwards any unrecognized flag automatically. - Cost tracking internals: The detailed algorithm for cost accumulation and the format of cost data files.
- MCP server protocol: The specific MCP tool definitions and protocol details when running in
--mcpmode. - Smoke test configuration: The
scripts/smoke/configuration for provider smoke tests. - Token file format: The internal token counting files used by
writeTokenFilefor the status line display.
Appendix: Quick Reference Card
# Install / verify
npm install -g claudish
claudish --version
# Interactive mode (model selector appears)
claudish
claudish --free # only free models
claudish -p myprofile # with specific profile
# Single-shot (no model selector)
claudish --model [email protected] "task"
claudish --model oai@gpt-4o "task"
claudish --model [email protected] "task"
# Model role mapping
claudish --model-opus g@gemini-3-pro --model-sonnet [email protected]
# Auto-approve + disable sandbox (CI/automation)
claudish -y --dangerous --model [email protected] "task"
# Debug
claudish --debug-claudish --model [email protected] "task"
# Profile management
claudish init
claudish profile list
claudish profile add --global
claudish profile use myprofile --global
# Model discovery
claudish --models # all models
claudish --models gemini # search
claudish --models-top # curated list
claudish --models --json # JSON output
# OAuth login
claudish --gemini-login
claudish --kimi-login
# Telemetry
claudish telemetry status
claudish telemetry off
This document was generated from direct codebase analysis of Claudish source at packages/cli/src/. Last updated for v7.0.0 (default provider, custom endpoints, routing rules catch-all synthesis). Key files: cli.ts, config.ts, model-parser.ts, provider-resolver.ts, auto-route.ts, remote-provider-registry.ts, profile-config.ts, routing-rules.ts.