/mulmoterminal-model

name: mulmoterminal-model
description: Run MulmoTerminal sessions on something other than Anthropic's default, three ways — register an Anthropic-compatible backend (OpenRouter, Moonshot, a local Ollama bridge, a company gateway) as a `providers` entry in `~/.mulmoterminal/config.json` (also added in Settings → Models and backends); pin a `provider` / `model` per project in its `.mulmoterminal.json`; or add a `customAgents` entry, your OWN command line for starting Claude Code (`ollama launch claude --model … --`, a wrapper script, a pinned binary), which then appears in the Agent Picker beside Claude / Codex / Antigravity / Grok / Shell and gets Claude Code's own arguments appended. Knows the measured pass rates of the built-in model list, and the misconfigurations that break a session in ways that are hard to diagnose from inside it (a trailing `/v1`, too small an output budget, an API key written to disk, a provider named but never registered, a custom agent that swallows the arguments it is handed). Use when the user wants to use OpenRouter, Kimi, GLM, DeepSeek, Qwen, a local or self-hosted model, a cheaper model, a different Anthropic model for one project, or to launch Claude Code through a command of their own, or to run some cells on a second Claude Code / Codex subscription (`accounts`) — or when a session refuses to start, returns empty replies, or 404s after they changed models.

Run on another model

The keys, and the job each one does:

• **`~/.mulmoterminal/config.json` → `providers`** — register a backend once. Also added and

removed in Settings → Models and backends, which refuses a `/v1` base URL and a key in place of the variable's name.

• **`<project>/.mulmoterminal.json` → `provider` / `model`** — what this project launches on.

Both are defaults; the launch form can override them for a single session. Also a select in Settings → Directory settings → Change here, which offers the models of the registered providers.

• **`~/.mulmoterminal/config.json` → `customAgents`** — the user's own COMMAND for starting Claude

Code, offered in the Agent Picker. For when the model is reached by running something else (`ollama launch claude …`, a wrapper script, a second Claude Code install) rather than by an HTTP endpoint. Also added and removed in Settings → Models and backends.

• **`~/.mulmoterminal/config.json` → `accounts`** — a SECOND LOGIN for Claude Code or Codex (another

subscription), kept in its own config directory and picked per cell in the launch form. Also added and removed in Settings → Models and backends.

• **`~/.mulmoterminal/config.json` → `tokenRotation`** — several Claude subscriptions behind the ONE

default config directory, with MulmoTerminal choosing which one each new session runs on so the weekly windows drain evenly. config.json only (beta).

• **`~/.mulmoterminal/config.json` → `defaultAgent`** (or `--agent <id>` on the command line) —

which of the seven agent CLIs a NEW cell starts as, and the only thing that relaxes the Claude-Code-required check at start-up (#2082). Also a select in Settings → Models and backends.

None is needed to use Anthropic's default. Only do this when the user asked for another model.

`defaultAgent` — which agent a new cell opens on

Start-up requires Claude Code **unless this is set**. Declaring an agent does two things and only two: the start-up check looks for THAT agent's binary instead of `claude`, and a new cell's Agent Picker starts on it.

{ "defaultAgent": "codex" }

`--agent codex` does the same for one launch and is NOT written back to the file. Settings → Models and backends → Default agent writes the same key, and offers an agent that is not installed only disabled. Valid ids: `claude`, `codex`, `antigravity`, `grok`, `muse`, `copilot`, `cursor`.

**It does not re-point anything that already exists.** A grid cell records its agent only when it is not Claude, so a saved Claude cell is stored as the ABSENCE of that field — which means Claude permanently, whatever `defaultAgent` later says. A browser that has already used the Agent Picker also keeps its remembered choice. This key seeds new things; it never rewrites old ones.

**Do not confuse it with `customAgents`.** `defaultAgent` picks among the seven built-in agents. `customAgents` adds a NEW Agent Picker entry that runs Claude Code through a command of your own.

**Which one.** A backend that speaks the Anthropic API over HTTP is a `providers` entry — that is the smaller change and it composes with the model picker. Reach for `customAgents` only when the thing that runs the model is a **command**, and the user cannot express it as a base URL and a token.

Registering a backend

{
  "providers": [
    {
      "id": "openrouter",
      "label": "OpenRouter",
      "baseUrl": "https://openrouter.ai/api",
      "tokenEnv": "OPENROUTER_API_KEY",
      "maxOutputTokens": 16000
    }
  ]
}

Each rule below was measured against a working setup, and each breaks the session in a way that is hard to diagnose from inside it:

• **`baseUrl` must not end in `/v1`.** Claude Code appends `/v1/messages` itself, so a trailing

`/v1` produces `/v1/v1/messages` and every request 404s.

• **Never write the API key into a config or skill file.** `tokenEnv` is the **name** of an

environment variable, not the value: the key reaches the server through its environment. Put it in the shell that starts the server, or in a `.env` in the directory it is started from — and if you write a `.env`, check it is gitignored before you do. If the user pastes a key at you, tell them where it goes; do not store it anywhere yourself.

• **Keep `maxOutputTokens` at 16000 or above.** A thinking model given less spends the whole budget

thinking and returns empty visible text, which reads as a hung session.

• **`models` is REQUIRED under any `id` other than `openrouter`.** Every preset in

`common/modelPresets.ts` carries `provider: