Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs(routing): document defaultProvider sources and the empty value

Jack Rudenko2f6f903a0fa3
diff --git a/ai-docs/architecture/routing.md b/ai-docs/architecture/routing.md
index 0b6420b9..62dc0f17 100644
--- a/ai-docs/architecture/routing.md
+++ b/ai-docs/architecture/routing.md
@@ -138,17 +138,50 @@ catalog maps is tried first.
Set it via:
-- **Config file**: `"defaultProvider": "openrouter"` in `~/.claudish/config.json`
+- **Config file**: `"defaultProvider": "openrouter"` in `~/.claudish/config.json`, or in the file
+ `--config` names
- **Env var**: `CLAUDISH_DEFAULT_PROVIDER=openrouter`
- **CLI flag**: `claudish --default-provider openrouter "task"`
-**Precedence** (highest to lowest):
+**Precedence** (highest to lowest), decided by one resolver, `resolveDefaultProvider`
+(`default-provider.ts`):
1. CLI flag `--default-provider`
2. `CLAUDISH_DEFAULT_PROVIDER` env var
-3. `defaultProvider` in config file
+3. `defaultProvider` in the config file
4. `OPENROUTER_API_KEY` present → `"openrouter"`
5. Hardcoded `"openrouter"`
+Steps 4 and 5 route identically. They differ only in the `source` the route-table gate records.
+
+**An empty value is an answer, not a gap.** `""` at step 1, 2 or 3 disables the fallback hop and
+stops the search there, so `CLAUDISH_DEFAULT_PROVIDER=` beats a config `x`, and a flag `x` beats
+an empty env var. Until 2026-09-24 the resolver skipped `""` and answered `openrouter`, so the
+documented off switch did not work from the env var at all.
+
+**Not read: a project `.claudish.json`.** `loadLocalConfig` keeps a `defaultProvider` key in the
+project file, but no routing path reads it: only the global config (or the `--config` file) is
+step 3. Supporting a project value would need a project source in the resolver, a scope in the
+config TUI's Routing header and its own interaction with `--config`, which nothing asks for yet.
+
+**How the flag travels.** `index.ts` strips `--default-provider` from argv and exports its value
+as `CLAUDISH_DEFAULT_PROVIDER` before `parseArgs` and before any subcommand runs
+(`planDefaultProviderFlag`). After that the env var is the flag's only carrier: `route()`, the
+proxy, `--probe` and every child claudish (team, channel sessions) read it there. It cannot be read
+any later, for two reasons: `--probe` runs and exits inside `parseArgs`'s argv loop, and a child
+process inherits env, not argv. `--default-provider ""` exports an empty value, which disables
+the hop. The export runs after `--op-env` and `--op`, which overwrite env unconditionally, so the
+flag still beats a value they hydrate. Children see it only because every claudish child is
+spawned through `node:child_process`, which inherits `process.env`: `Bun.spawn` without an `env`
+option drops in-process env writes.
+
+**Who reads it.** `route(model)` with no overrides asks the resolver on every call
+(`effectiveDefaultProvider`), and so does `--probe`'s chain, so the two cannot name different
+fallback hops. The proxy resolves it once at start and passes it as `route()`'s third argument. It
+has to: the proxy also passes its routing rules, and `route(model, rules)` with no third argument
+reads NO default provider, a guard that keeps the machine's setting out of unit tests. Until
+2026-09-24 the proxy passed only the rules, so its bare-name routing fell back to `openrouter`
+whatever `defaultProvider` said, `""` included.
+
**Example config**:
```json
{
@@ -157,7 +190,8 @@ Set it via:
}
```
-Valid values: any built-in provider name (`"openrouter"`, `"openai"`, `"google"`, `"litellm"`, etc.) or a custom endpoint name defined in `customEndpoints`.
+Valid values: any claudish provider name or shortcut (`"openrouter"`, `"or"`, `"openai"`,
+`"litellm"`, etc.), a custom endpoint name defined in `customEndpoints`, or `""` for none.
**How it interacts with routing rules**: it applies ONLY to the catalog-gathered path. A bare
name that matched a user rule gets that chain verbatim with no fallback appended — which is what
@@ -170,7 +204,7 @@ whole chain is credential-filtered. Explicit `provider@model` specs are unaffect
| Setting | Fallback hop |
|---|---|
| unset (`undefined`) | `openrouter` — "no preference" is not "disabled" |
-| `""` (explicit empty string) | none |
+| `""` (explicit empty string), from the flag, the env var or the config file | none |
| a matching user rule, e.g. `routing["*"] = []` | none — the rule is verbatim |
**It is not appended when the catalog positively denies it.** The catalog draws the line itself:
@@ -189,7 +223,7 @@ partial by nature — `openai-codex` appears on 5 rows of 1,123). The route-owne
what makes the narrower question answerable, and only the fallback APPEND asks it: the
difference is inventing a hop nobody published versus dropping one something else put there.
-**No more LiteLLM auto-promotion** (removed in commit 5 of the model-catalog and routing redesign): Setting `LITELLM_BASE_URL` + `LITELLM_API_KEY` no longer makes LiteLLM the default. Users who want LiteLLM as the catch-all must set `defaultProvider: "litellm"` explicitly.
+**No more LiteLLM auto-promotion** (removed in commit 5 of the model-catalog and routing redesign): Setting `LITELLM_BASE_URL` + `LITELLM_API_KEY` no longer makes LiteLLM the default. Users who want LiteLLM as the catch-all must set `defaultProvider: "litellm"` explicitly. The one-shot stderr hint that announced the promotion, and the `DefaultProviderSchema` that listed LiteLLM as a built-in name, are gone as well.
## Vendor Prefix Auto-Resolution (ModelCatalogResolver)
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 5da4131c..39a73063 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -2343,14 +2343,16 @@ ${h("MODEL ROUTING")}
${yellow("anthropic/*, claude-*")} ${dim("->")} Native Anthropic
${yellow("(unknown vendor/)")} ${dim("->")} Error (use openrouter@vendor/model)
- ${dim("A defaultProvider (config / --default-provider) catches bare names that match no rule.")}
+ ${dim("A defaultProvider (--default-provider / CLAUDISH_DEFAULT_PROVIDER / config) is the last hop for")}
+ ${dim('bare names that match no rule. "" disables it.')}
${h("OPTIONS")}
${green("-i, --interactive")} Run in interactive mode (default when no prompt given)
${green("-m, --model")} ${yellow("<model>")} Model to use (required for single-shot mode)
${green("--profile")} ${yellow("<name>")} Use named profile for model mapping (default profile if omitted)
- ${green("--default-provider")} ${yellow("<name>")} Fallback provider for bare model names (builtin or customEndpoints key)
- ${dim("Precedence: this flag > CLAUDISH_DEFAULT_PROVIDER env > config.json")}
+ ${green("--default-provider")} ${yellow("<name>")} Fallback provider for bare model names (claudish provider or customEndpoints key)
+ ${dim('"" disables it. Precedence: this flag > CLAUDISH_DEFAULT_PROVIDER env > config.json')}
+ ${dim("(the global config or the --config file; a project .claudish.json is not read)")}
${green("--anthropic-api-billing")} Use your real ANTHROPIC_API_KEY for native Claude models
${dim("(metered API billing). Default: the key is hidden so Claude Code")}
${dim("uses your claude.ai subscription. Env: CLAUDISH_ANTHROPIC_API_BILLING")}
@@ -2540,7 +2542,7 @@ ${h("ENVIRONMENT VARIABLES")}
${bold("Claudish settings:")}
${blue("CLAUDISH_MODEL")} Default model ${dim("(default: openai/gpt-5.3)")}
- ${blue("CLAUDISH_DEFAULT_PROVIDER")} Fallback provider for bare names ${dim("(see --default-provider)")}
+ ${blue("CLAUDISH_DEFAULT_PROVIDER")} Fallback provider for bare names; empty disables it ${dim("(see --default-provider)")}
${blue("CLAUDISH_PORT")} Default proxy port
${blue("CLAUDISH_CONTEXT_WINDOW")} Override context window size
${blue("CLAUDISH_DIAG_MODE")} Diagnostic output: auto / logfile / off
diff --git a/packages/cli/src/profile-config.ts b/packages/cli/src/profile-config.ts
index 924b6c45..d44012b8 100644
--- a/packages/cli/src/profile-config.ts
+++ b/packages/cli/src/profile-config.ts
@@ -196,10 +196,20 @@ export interface ClaudishProfileConfig {
debug?: boolean;
/**
- * Default provider for bare model names. One of the builtin names
- * (openrouter, litellm, openai, anthropic, google) or a key from `customEndpoints`.
- * Precedence: --default-provider flag > CLAUDISH_DEFAULT_PROVIDER env > this field.
- * Phase 2 wires this into the routing fallback chain.
+ * The provider in the FALLBACK position: the last hop of a bare name's
+ * catalog-gathered chain. A claudish provider name or shortcut, or a
+ * `customEndpoints` key. Not used for an explicit `provider@model` spec, nor when
+ * a user routing rule matches (that chain is used verbatim).
+ *
+ * - unset: `openrouter`.
+ * - `""`: no fallback hop. A name the catalog does not serve gets no route.
+ *
+ * Precedence (`resolveDefaultProvider`): `--default-provider` flag >
+ * CLAUDISH_DEFAULT_PROVIDER env > this field. An empty flag or env value is an
+ * answer too: it disables the hop and overrides this field.
+ *
+ * Read from the global config (or the `--config` file) only. A `defaultProvider`
+ * in a project `.claudish.json` is kept on disk, but no routing path reads it.
*/
defaultProvider?: string;