command-code 1.28.4 → 1.30.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # command-code
 
+## 1.30.0
+
+### Minor Changes
+
+- feat: BYOK providers support (beta)
+- /connect menu to manage provider connections
+- feat(providers): local-only mode for byok
+
+## 1.29.0
+
+- feat: improve traffic routing
+
 ## 1.28.4
 
 ### Patch Changes

package/dist/bundled/command-code-knowledge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: command-code-knowledge
-description: Authoritative Command Code product knowledge — slash commands, CLI options, permissions, skills, custom agents, MCP servers, hooks, memory, headless mode, plan mode, checkpoints, sessions, the model catalog, taste, pricing, and troubleshooting. Use when the user asks how Command Code works, how to configure or extend it, which models exist, or when you need product facts to answer a "can Command Code do X" question. Do NOT search the codebase for product behavior — read the reference files here instead.
+description: Authoritative Command Code product knowledge — slash commands, CLI options, permissions, skills, custom agents, MCP servers, hooks, memory, headless mode, plan mode, checkpoints, sessions, the model catalog, custom/BYOK providers (providers.json, OpenAI-compatible and Anthropic-wire endpoints, local servers like Ollama, API keys, /providers), taste, pricing, and troubleshooting. Use when the user asks how Command Code works, how to configure or extend it, which models exist, how to add their own provider or endpoint, or when you need product facts to answer a "can Command Code do X" question. Do NOT search the codebase for product behavior — read the reference files here instead.
 ---
 
 # Command Code Knowledge
@@ -22,13 +22,19 @@ the matching reference file.
    limits): read `reference/plans.md` and the Min plan column in `reference/models.md`. The
    plan itself is not readable headlessly — ask the user or point them at /usage. Never
    dig through auth files, API endpoints, or TTY tricks.
-5. Anything about the help surface (slash commands, keyboard shortcuts, CLI flags, taste,
+5. Custom/BYOK provider questions (the providers.json shape, `apiKey` references, local
+   endpoints like Ollama/vLLM/LM Studio, `/providers`, "add X as a provider"): read
+   `reference/byok.md`. Never invent config keys — the accepted fields are listed there
+   verbatim. When you need current model ids, context windows, or prices for an EXTERNAL
+   provider, fetch the models.dev registry (https://models.dev/api.json — the same catalog
+   the CLI's /providers wizard uses) rather than inventing them.
+6. Anything about the help surface (slash commands, keyboard shortcuts, CLI flags, taste,
    FAQ, pricing links): `reference/product-help.md` — the same document the
    bundled product-help reference.
-6. Questions about the built-in tools — exact wire names, parameters, guards, limits, or how
+7. Questions about the built-in tools — exact wire names, parameters, guards, limits, or how
    the agent is expected to drive one (e.g. the worked `todo_write` checklist examples):
    `reference/tools.md`.
-7. Building a mod (a loadable ModApi plugin)? Switch to the `mod-builder` skill — it has
+8. Building a mod (a loadable ModApi plugin)? Switch to the `mod-builder` skill — it has
    the mods reference and runnable examples.
 
 ## Reference index
@@ -45,6 +51,7 @@ the matching reference file.
 - `reference/headless.md` — Headless Mode
 - `reference/plan-mode.md` — Plan Mode
 - `reference/sessions.md` — Sessions & Checkpoints
+- `reference/byok.md` — BYOK
 - `reference/models.md` — Command Code Models
 - `reference/plans.md` — Plans, credits, and per-plan model access
 - `reference/product-help.md` — Product help (slash commands, CLI, taste, FAQ, pricing)

package/dist/bundled/command-code-knowledge/reference/byok.md

@@ -0,0 +1,356 @@
+<!-- Generated from the Command Code docs: https://commandcode.ai/docs -->
+
+# BYOK
+
+BYOK is currently in beta and subject to improvements.
+
+Bring your own provider and use it in Command Code CLI. Any OpenAI or Anthropic compactible API can serve models in Command Code. You can bring your key from hosted providers (DeepSeek, OpenRouter, Vercel AI Gateway), local servers (Ollama, vLLM), or other coding agent's APIs.
+
+## BYOK Providers
+
+You can connect to any external provider in Command Code, requests go straight from your machine to that provider's endpoint with your key, never through Command Code's servers.
+
+BYOK providers can be managed from `/connect` in the Command Code CLI. Below are providers and instructions on how to connect to them.
+
+---
+
+## Command Code
+
+Command Code is the default and recommended provider. Every model in `/model` routes through your plan, and the models are optimized for the cmd harness. That optimization is real engineering: see [Harness Engineering](https://commandcode.ai/docs/harness-engineering) for how the harness repairs, steers, and optimizes models.
+
+The `/model` menu can be used to access models from Command Code and BYOK providers. BYOK models are active alongside Command Code models, and you switch back to Command Code models anytime through the model menu.
+
+---
+
+## OpenAI ChatGPT/Codex
+
+You can use your ChatGPT Pro/Plus subscription directly in Command Code. Select **OpenAI ChatGPT/Codex** in `/connect` (or run `cmd login openai`, `chatgpt` works too) and sign in.
+
+The provider package installs on demand at first login, and its models appear as their own section in `/model`. Requests run locally from the CLI over your subscription.
+
+---
+
+## GitHub Copilot
+
+Same flow for an active GitHub Copilot subscription: select **GitHub Copilot** in `/connect` (or `cmd login copilot`), complete the device sign-in, and the copilot provider's models will be listed in `/model`.
+
+---
+
+## Adding a custom provider
+
+The `/connect` menu supports **150+ providers** out of the box. For those, the endpoint, wire, and current model list come prefilled. Anything else works too: any OpenAI-compatible or Anthropic-wire endpoint can also be setup.
+
+Run `/connect` and pick **(BYOK) Add your own provider**.
+
+### From the supported providers list (the happy path)
+
+The connect menu supports 150+ providers with endpoint, models, and config prefilled. You can search and pick a provider from this menu.
+
+**Pick the provider**
+Start typing at the id step (`openrouter`, `deepseek`, `groq`, …) and a browsable list of known providers shows under the input. Pick one with `↑/↓` + enter; the wire and endpoint prefill.
+
+**Paste your key**
+Keys are stored securely in `~/.commandcode/auth.json`. Press enter on the empty field if the endpoint takes no key (local servers).
+
+**Models arrive on their own**
+Discovery is silent: the provider's current model list, names and context windows included, is imported for you. Finishing lands you in `/model` with the new models selectable and routing.
+
+### Not in the list (fully custom)
+
+If your provider is not in the menu, or you want to declare a custom/local one, follow these steps:
+
+**Name it**
+Type any id, a short lowercase handle (`work-llm`). It names the entry in `~/.commandcode/providers.json` and prefixes its models (`work-llm/gpt-x`).
+
+**Pick the wire**
+**OpenAI-compatible** (`/chat/completions`, the default: Ollama, vLLM, LM Studio, most hosted APIs) or **Anthropic** (`/v1/messages`, for endpoints speaking the Claude Messages API).
+
+**Point at the endpoint**
+The API root. OpenAI-compatible servers usually end in `/v1`; Anthropic roots get `/v1` added on the wire when missing. A pasted URL carrying a route suffix (`…/v1/chat/completions`) is trimmed to the root automatically, with a note showing what was removed.
+
+**Add the key, or skip it**
+Key is securely stored in `auth.json`. Press enter on the empty field if the endpoint takes no key (local servers).
+
+**Declare the models**
+The menu asks the endpoint's own `/models` listing first. If that comes up empty, you can either type ids there or modify the providers.json file to add the models. See the config schema below for details.
+
+Press `h` on any non-typing step for the condensed version of all of this; `esc` (or `←` where it can't mean cursor movement) goes back one step.
+
+You can also just ask the agent: `add OpenRouter as a provider and enable deepseek/deepseek-v4-flash`. It reads its bundled BYOK reference, looks up current model ids and context windows when it needs them, and writes the `providers.json` entry for you. Review it like any other edit.
+
+---
+
+## Provider config schema
+
+Everything related to byok providers lives in `~/.commandcode/providers.json`. It is yours to edit, and changes apply live (reopen `/connect` or `/model`). For example:
+
+```json
+// ~/.commandcode/providers.json
+{
+  "provider": {
+    "novita": {
+      "name": "Novita",
+      "baseURL": "https://api.novita.ai/v3/openai",
+      "apiKey": "$NOVITA_API_KEY",
+      "models": {
+        "qwen/qwen3.6-27b": {
+          "name": "Qwen 3.6 27B",
+          "contextWindow": 131072,
+          "maxOutput": 16384,
+          "reasoningEfforts": ["low", "high"],
+          "cost": { "input": 0.4, "output": 1.6 },
+          "options": { "temperature": 0.6 }
+        }
+      }
+    },
+    "claude-proxy": {
+      "api": "anthropic-messages",
+      "baseURL": "https://api.novita.ai/anthropic",
+      "apiKey": "$NOVITA_API_KEY",
+      "models": { "minimax/minimax-m2.7": {} }
+    },
+    "ollama": {
+      "baseURL": "http://localhost:11434/v1",
+      "apiKey": false,
+      "models": { "llama3.3:70b": {} }
+    }
+  }
+}
+```
+
+### Provider fields
+
+| Field | Values | Notes |
+| --- | --- | --- |
+| `name` | string | Display name in `/connect` and `/model`; defaults to the id |
+| `api` | `openai-completions` (default) \| `anthropic-messages` | Omit for OpenAI-compatible endpoints. Any other value skips the provider |
+| `npm` | AI-SDK package name | Compat only: `@ai-sdk/openai-compatible` & `@ai-sdk/openai` map to `openai-completions`, `@ai-sdk/anthropic` to `anthropic-messages`; any other package warns and assumes `openai-completions`. Ignored when `api` is set. |
+| `baseURL` | URL | Required. The API root requests go to. Missing or invalid URL skips the provider. Also read from `options.baseURL` (top-level wins) |
+| `apiKey` | `"$ENV_VAR"` \| `"{env:VAR}"` \| `"!command"` \| `false` | A key saved via `/connect` wins over this field. It is reference to the key, never the key itself. `"$VAR"` and `"{env:VAR}"` read that env variable; `"!command"` runs the command and uses its output; `false` = keyless endpoint, no auth header sent. A pasted raw secret is refused with a warning. |
+| `headers` | object | Extra request headers, string values only. One non-string value drops the whole object with a warning |
+| `models` | object | Required. `{}` per id is enough. Zero valid models skips the provider |
+| `disabled` | `true` | Tombstone: the entry is skipped silently, no warning. `"enabled": false` means the same |
+
+### Model fields
+
+Every field is optional but we recommend adding `contextWindow` as a bare minimum. `"a-model-id": {}` is a complete declaration:
+
+| Field | Values | Notes |
+| --- | --- | --- |
+| `name` | string | Display name in `/model` |
+| `contextWindow` | number > 0 | Tokens. Compat alias: `limit.context` (`contextWindow` wins when both are set)  Default: 200K|
+| `maxOutput` | number > 0 | Tokens. Compat alias: `limit.output` |
+| `reasoning` | boolean | `true` assumes the efforts `low` / `medium` / `high`; `false` declares none |
+| `reasoningEfforts` | string[] | Exact valid set: `low` \| `medium` \| `high` \| `xhigh` \| `max`. Unknown levels are dropped with a warning naming that set |
+| `cost` | object | $ per 1M tokens: `input`, `output`, `cacheRead`, `cacheWrite` (snake_case `cache_read` / `cache_write` accepted); `0` is valid for free models |
+| `options` | object | Extra request-body params merged into every call for this model (`temperature`, `top_p`, …) |
+
+A non-object model value skips that model with a warning; sibling models survive.
+
+---
+
+## Example provider config
+
+Below are examples of BYOK providers added in `~/.commandcode/providers.json`. Command Code is the default provider, nothing to declare for it.
+
+**OpenRouter**
+
+```json
+// ~/.commandcode/providers.json
+{
+  "provider": {
+    "openrouter": {
+      "name": "OpenRouter",
+      "baseURL": "https://openrouter.ai/api/v1",
+      "apiKey": "$OPENROUTER_API_KEY",
+      "models": { "deepseek/deepseek-v4-flash": {} }
+    }
+  }
+}
+```
+
+**Vercel AI Gateway**
+
+```json
+// ~/.commandcode/providers.json
+{
+  "provider": {
+    "vercel": {
+      "name": "Vercel AI Gateway",
+      "baseURL": "https://ai-gateway.vercel.sh/v1",
+      "apiKey": "$AI_GATEWAY_API_KEY",
+      "models": { "deepseek/deepseek-v4-flash": {} }
+    }
+  }
+}
+```
+
+**Cloudflare AI Gateway**: its OpenAI-compatible root carries your account and gateway ids, and model ids are `provider/model` as the gateway spells them:
+
+```json
+// ~/.commandcode/providers.json
+{
+  "provider": {
+    "cf-gateway": {
+      "name": "Cloudflare AI Gateway",
+      "baseURL": "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/compat",
+      "apiKey": "$CF_AI_GATEWAY_TOKEN",
+      "models": { "anthropic/claude-sonnet-4-6": {} }
+    }
+  }
+}
+```
+
+**Hugging Face router**
+
+```json
+// ~/.commandcode/providers.json
+{
+  "provider": {
+    "huggingface": {
+      "name": "Hugging Face",
+      "baseURL": "https://router.huggingface.co/v1",
+      "apiKey": "$HF_TOKEN",
+      "models": { "Qwen/Qwen3.6-27B-Instruct": {} }
+    }
+  }
+}
+```
+
+**Ollama (local, keyless)**
+
+```json
+// ~/.commandcode/providers.json
+{
+  "provider": {
+    "ollama": {
+      "baseURL": "http://localhost:11434/v1",
+      "apiKey": false,
+      "models": { "llama3.3:70b": {} }
+    }
+  }
+}
+```
+
+---
+
+## Managing a provider
+
+Selecting a custom provider in `/connect` opens its card: the endpoint, its declared model count (with a clickable `config: providers.json` link straight to the file), the key situation, and the actions that fit.
+
+| Key state | Card shows | Actions |
+| --- | --- | --- |
+| Stored key | `key sk_… ✓ stored in auth.json` | enter save · `r` replace key · `c` clear · `u` update models · `d` delete |
+| File reference | `key $VAR` | `r` store key · `u` update models · `d` delete |
+| Keyless | `no key — the endpoint asks for none` | `r` store key · `u` update models · `d` delete |
+| No key yet | `no key yet — requests fail until one is added` | enter add key · `u` update models · `d` delete |
+
+In the `/connect` menu itself, a healthy provider row shows a green ✓ with its model count. Only `○ needs a key` appears when requests would fail without action.
+
+Update `u` refetches the provider's model list (registry first, the endpoint's `/models` as fallback) and updates the provider's models. The key reference, headers, and wire are untouched.
+
+Delete `d` removes the provider. It is deleted from providers.json, its stored key is cleared, and its models leave `/model` immediately; if it owned your active model, the session switches to the default model.
+
+---
+
+## Invalid config
+
+If there is a malformed entry in providers config, it never breaks its siblings. It's skipped with a specific warning shown under the `/connect` list and on `--list-models`:
+
+```
+providers.json needs attention — one entry did not load as written:
+provider.work-llm: no baseURL configured — provider skipped
+```
+
+An unreadable or unparseable file warns the same way (`providers config <path>: invalid JSON (details redacted)`). Your providers vanish for that run instead of crashing the CLI. The `/connect` writers never touch a file they can't parse: an add, model refetch, or remove against broken JSON refuses with nothing written.
+
+---
+
+## Local-only mode
+
+For setups that must never contact Command Code's backend at all (a team running the CLI against their own endpoints, CI fleets, or other environments), they can turn on local-only mode:
+
+```bash
+cmd --local-only
+# or via the environment:
+CMD_LOCAL_ONLY=1 cmd
+```
+
+or persist it in `~/.commandcode/config.json`:
+
+```json
+{ "localOnly": true }
+```
+
+What it guarantees:
+
+- **No telemetry, anywhere.** Trace exporters, lifecycle events, telemetry identity, and machine fingerprinting are all off. (`DO_NOT_TRACK=1` also stops all of these, including fingerprinting; local-only additionally blocks the non-telemetry backend traffic below.)
+- **No billing reads.** The plan/credits prefetches never run; model pickers treat the absent plan as unrestricted and your providers gate access themselves.
+- **A refusal transport.** The session's backend transport is replaced with one that throws a clear `LocalOnlyError` naming the route and the switch. Nothing can reach Command Code including a model id that would otherwise fall through to the Command Code provider.
+
+What stops working, by design: Command Code catalog (gateway) models, `/share`, `/usage`, the server-proxied `web_search`/`web_fetch` tools, `cmd taste push`/`pull`, and backend agent generation. Your BYOK providers, and everything local keep working exactly as before.
+
+---
+
+## FAQs
+
+                    Your BYOK session model, for everything. Compaction and summarization, sub-agents, title generation: all the side tasks default to the session model while a BYOK model is active, so nothing silently falls back to Command Code (or bills your plan) mid-session.
+                </p>
+            )
+        },
+        {
+            id: 'faq-keys-storage',
+            question: 'Where are my API keys stored?',
+            answer: (
+                <p>
+                    Keys pasted in <code>/connect</code> live in <code>~/.commandcode/auth.json</code> (written <code>0600</code>), each under its provider's id, beside your Command Code login and subscription tokens. Logging out of Command Code strips only the account fields. Provider keys survive. Update a key any time with <code>r</code> on the provider's card in the /connect menu.
+                </p>
+            )
+        },
+        {
+            id: 'faq-keys-providers-json',
+            question: 'Can I put a key directly in providers.json?',
+            answer: (
+                <p>
+                    Only as a reference: <code>"$ENV_VAR"</code>, <code>"&#123;env:VAR&#125;"</code>, or <code>"!command"</code> (see the schema above). A raw secret pasted into the file is refused at parse with a warning; the provider survives, only the key is ignored. Per request, a stored key wins over the file's reference.
+                </p>
+            )
+        },
+        {
+            id: 'faq-customize',
+            question: 'How do I customize a provider or its models?',
+            answer: (
+                <p>
+                    Edit <code>~/.commandcode/providers.json</code>. The full schema is documented above, and changes apply live (reopen <code>/connect</code> or <code>/model</code>). Per model you can set the display name, context window, max output, reasoning efforts, cost, and extra request-body <code>options</code> like temperature. Per provider: headers, the wire (<code>api</code>), and the endpoint.
+                </p>
+            )
+        },
+        {
+            id: 'faq-same-id',
+            question: 'What if a model id exists on Command Code and my provider?',
+            answer: (
+                <p>
+                    Both stay selectable. <code>/model</code> shows each under its own heading, and picking a row routes exactly where its heading says. Two of your own providers sharing an id works the same way: each qualified model id owns its route.
+                </p>
+            )
+        },
+        {
+            id: 'faq-project-scope',
+            question: 'Can a project or repo define its own providers?',
+            answer: (
+                <p>
+                    No. BYOK providers are set only on the user-level, with config stored globally at <code>~/.commandcode/providers.json</code>.
+                </p>
+            )
+        },
+        {
+            id: 'faq-privacy',
+            question: 'Do BYOK requests or my keys ever touch Command Code?',
+            answer: (
+                <p>
+                    No. Requests go straight from your machine to your endpoint, and keys never leave it. The only thing emitted is a trimmed telemetry span: model id, provider id, usage, latency, and finish reason. Never prompts, keys, endpoint URLs, or errors after scrubbing. <code>DO_NOT_TRACK=1</code> or local-only mode turns even that off.
+                </p>
+            )
+        }
+    ]}
+/>

package/dist/bundled/command-code-knowledge/reference/custom-slash-commands.md

@@ -77,7 +77,7 @@ Every built-in command, grouped by area. Aliases are shown in parentheses on the
 | ----------------- | ---------------------------------------------------------------------------------------- |
 | `/model [id]`     | Switch between Command Code models - `/model <id>` applies directly, bare opens a picker |
 | `/effort [level]` | Set reasoning effort for the current model (levels depend on the model)                  |
-| `/provider`       | Select AI provider (Command Code or Anthropic)                                           |
+| `/connect`      | Connect to AI providers. Command Code, [BYOK providers](./byok.md) and API keys |
 | `/login`          | Log in to Command Code or a provider                                                     |
 | `/logout`         | Log out of Command Code or a provider                                                    |
 

package/dist/bundled/command-code-knowledge/reference/models.md

@@ -57,7 +57,7 @@ The model catalog — every id `/model`, `--model`, `model:effort` shorthand, an
 | `gpt-5.6-sol` | GPT-5.6 Sol | 1.05M | low, medium, high, xhigh, max | $5/$30 · cache $0.5 (write $6.25) | GOAT and above | frontier model for complex professional work |
 | `gpt-5.6-terra` | GPT-5.6 Terra | 1.05M | low, medium, high, xhigh, max | $2/$12 · cache $0.2 (write $2.5) | Pro and above | balances intelligence and cost |
 | `gpt-5.6-luna` | GPT-5.6 Luna | 1.05M | low, medium, high, xhigh, max | $0.2/$1.2 · cache $0.02 (write $0.25) | Go and above | optimized for cost-sensitive workloads |
-| `gpt-5.5` | GPT-5.5 | — | low, medium, high, xhigh | $5/$30 · cache $0.5 (write $0) | Pro and above | latest frontier model for general complex work |
+| `gpt-5.5` | GPT-5.5 | 400K | low, medium, high, xhigh | $5/$30 · cache $0.5 (write $0) | Pro and above | latest frontier model for general complex work |
 | `gpt-5.4` | GPT-5.4 | 400K | low, medium, high, xhigh | $2.5/$15 · cache $0.25 (write $0) | Pro and above | frontier model for general complex work |
 | `gpt-5.3-codex` | GPT-5.3 Codex | 400K | low, medium, high, xhigh | $2/$8 · cache $0.5 (write $0) | Pro and above | frontier coding model |
 | `gpt-5.4-mini` | GPT-5.4 Mini | 400K | low, medium, high | $0.75/$4.5 · cache $0.075 (write $0) | Pro and above | fast, cost-effective model for everyday tasks |

package/dist/bundled/command-code-knowledge/reference/product-help.md

@@ -36,7 +36,7 @@
 - /mcp: Manage MCP server connections
 - /model: Switch between Command Code models
 - /effort: Set reasoning effort for the current model
-- /provider: Select AI provider (Command Code or Anthropic)
+- /connect: Connect to AI providers. Command Code, BYOK providers and API keys
 - /compact: Compact the conversation history
 - /compact-mode: Select a compact mode to compact sessions
 - /config: Search and change settings, including which model runs each built-in task
@@ -123,6 +123,7 @@
 - --theme <theme>: Set the color theme (dark or light)
 - --config <key=value>: Set any setting headlessly, e.g. --config theme=dark (repeatable) — the CLI form of /config
 - --list-models: List the models available for use
+- --local-only: For BYOK: local-only with your BYOK providers, no Command Code traffic (same as CMD_LOCAL_ONLY=1)
 - --plan: Start in plan mode
 - --permission-mode <mode>: Set permission mode (standard, plan, auto-accept)
 - --auto-accept: Start in auto-accept mode

package/dist/bundled/config/references/settings.md

@@ -10,7 +10,6 @@ The executable registry is authoritative. Run `cmd config list --scope effective
 | `permissions.defaultMode` | user | enum | `default`, `plan`, `auto-accept`, `dont-ask` | Default permission mode for tool usage. A long-lived host may also apply the change to its current session. "bypass" cannot be set here. |
 | `theme` | user | enum | `dark`, `light`, `auto` | Terminal color theme (same setting as /theme). Auto automatically detects your terminal background and uses light or dark to match. |
 | `compact-mode` | user | enum | `default`, `fast` | Auto-compact aggressiveness when context fills up (same setting as /compact-mode). |
-| `force-oauth` | user | boolean | `true`, `false` | Require OAuth login and block API-key authentication. |
 | `tree-filter-mode` | user | enum | `default`, `no-tools`, `user-only`, `labeled-only`, `all` | Default filter when opening /tree. |
 | `on-demand-tool-descriptions` | user | boolean | `true`, `false` | Explain shell commands on permission prompts only when you press ctrl+e (default). Turn off to generate every explanation upfront. |
 | `image-vision` | user | enum | `ask`, `enabled`, `disabled` | Let a text-only model read attached images by describing them with the vision model ("Ask on first use" prompts the first time you attach an image). |