Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs(agents): where the picker's models come from, the models.json cache, and what a built-in list with a reason means

Shahriar6fdece173c0f
diff --git a/docs/guide/agents.md b/docs/guide/agents.md
index 3323306..0755d47 100644
--- a/docs/guide/agents.md
+++ b/docs/guide/agents.md
@@ -19,12 +19,36 @@ own; picking a model is remembered per agent and applies from the next instructi
agents, changing the model keeps the conversation being held open — every CLI resumes a session
under a new model.
+### Where the models come from
+
+Where a CLI can say which models your account has, the select offers those:
+
+| Agent | Read from |
+| --- | --- |
+| Codex | the model cache Codex keeps itself, `~/.codex/models_cache.json` |
+| Antigravity | `agy models` |
+| Grok Build | `grok models` |
+| Cursor CLI | `cursor-agent models` — over 200, so the select becomes a filter, with Browsentic's picks first |
+
+The other four have no such command, so the select offers a short list Browsentic ships. For Claude
+Code those are its aliases — `fable`, `opus`, `sonnet`, `haiku` — which it resolves to the newest
+model of each family.
+
+The daemon reads a list in the background and never holds the popup up for one. A list it has read
+is kept for six hours, and read again at once when the CLI is updated; *Recheck* reads it again now.
+When a read fails — the CLI is signed out, times out, or prints something Browsentic cannot parse —
+the last list that read cleanly stays, or the shipped one when there is none, and the line under the
+select says why. A model you pinned yourself is never changed: if the CLI stops listing it, it stays
+selected, marked *not listed*.
+
The same thing from a terminal:
```sh
browsentic agent # what is installed, and what runs the side panel
browsentic agent codex # switch
browsentic agent fix antigravity
+browsentic agent models cursor # the models the select offers, and where they came from
+browsentic agent models cursor --refresh
```
Switching takes effect on the next instruction. It also drops the conversation being held open:
@@ -39,7 +63,7 @@ agents cannot resume each other's sessions, so the next instruction starts a fre
| Vendor | Anthropic | OpenAI | Google | Mistral AI | xAI | Anysphere | Alibaba | Anomaly |
| Binary | `claude` | `codex` | `agy` | `vibe` | `grok` | `cursor-agent` | `qwen` | `opencode` |
| Install | `npm i -g @anthropic-ai/claude-code` | `npm i -g @openai/codex` | [antigravity.google/docs/cli/install](https://antigravity.google/docs/cli/install) | `uv tool install mistral-vibe` | `curl -fsSL https://x.ai/cli/install.sh \| bash` | `curl https://cursor.com/install -fsS \| bash` | `npm i -g @qwen-code/qwen-code` | `npm i -g opencode-ai` |
-| Default model | `claude-sonnet-5` | the CLI's own | the CLI's own | the CLI's own | the CLI's own | the CLI's own | the CLI's own | the CLI's own |
+| Default model | `sonnet`, the newest Sonnet | the CLI's own | the CLI's own | the CLI's own | the CLI's own | the CLI's own | the CLI's own | the CLI's own |
| Effort names | `low`…`max` | `low`…`xhigh` | `low`…`high` | none — set `thinking` in Vibe's own config | `low`…`xhigh` | none — put it in the model id, e.g. `claude-opus-4-8[effort=high]` | none — the model id is the only lever | a variant the model defines, e.g. `high` or `max` |
| Kept off your machine by | a per-run tool allowlist plus an explicit deny list | a read-only sandbox (`sandbox_mode="read-only"`) | its own permission rules | a per-run tool allowlist — its shell and file tools are never loaded | a per-run tool list, approvals that refuse anything not granted up front, and a kernel sandbox that keeps its writes in its own folder | per-run deny rules, where a deny beats every allow; a kernel sandbox is asked for too but not depended on | `--safe-mode`, which drops every setting of your own, plus deny rules for the shell, the disk and the tools that reach either | a per-run agent whose rules deny every tool not named for it, so the model is never offered the shell, the disk or another server's tools |
@@ -236,7 +260,7 @@ In `~/.browsentic/config.json`:
| --- | --- | --- |
| `agent` | `claude` | Which CLI the side panel runs on. The agent picker writes this. |
| `agents.<name>.bin` | the CLI's own command name | Absolute path to the binary. Set this when the daemon's `PATH` differs from your shell's — the usual cause of `AGENT_MISSING`. |
-| `agents.<name>.model` | `claude-sonnet-5` for Claude, otherwise the CLI's own default | Passed as `--model`. The picker's model select writes this. |
+| `agents.<name>.model` | `sonnet` for Claude, otherwise the CLI's own default | Passed as `--model`. The picker's model select writes this. A value that starts with a dash or holds a space is ignored, so a typo cannot pass the CLI a flag. |
| `agents.<name>.effort` | unset | Passed as that CLI's reasoning-effort flag. A value the CLI does not accept is dropped rather than failing the run. |
Changes apply to the next run — the config is re-read each time, no daemon restart needed.
@@ -266,6 +290,8 @@ Claude runner's settings.
| `AGENT_UNSAFE`: *Qwen Code registered …* or *loaded the MCP server …* | Qwen's own `init` line named a tool or a server Browsentic denied, so the run was stopped. Update Qwen Code and Browsentic, and report it if it persists. |
| OpenCode: *free models refuse a run whose tools Browsentic has narrowed to the browser* | Zen's free tier serves only requests carrying OpenCode's own tools. Run `opencode auth login`, then pick that provider's model in the popup. |
| OpenCode: *could not start this turn* | Usually a model OpenCode does not know. Pick one as `opencode models` lists it, `provider/model`. |
+| The model select says *built-in list*, with a reason | Browsentic could not read that CLI's own list, usually because it is signed out. Sign it in, then press *Recheck*. The shipped list works meanwhile. |
+| A model shows *not listed* | You pinned it, and the CLI no longer lists it. It is still passed to the CLI; pick a listed one if runs start failing. |
| OpenCode cannot find a key you have exported | Only `OPENCODE_*` reaches a run. Run `opencode auth login` instead, which keeps the key in OpenCode's own file. |
| `AGENT_UNSAFE`: *OpenCode ran its own … tool* | A tool outside the browser ran despite the run's rules, so the run was stopped. Update OpenCode and Browsentic, and report it. |
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 4344a70..937ba17 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -51,9 +51,12 @@ Nothing here is required; this shows every key in one place.
| --- | --- | --- |
| `agent` | `claude` | Which CLI the side panel runs on: `claude`, `codex`, `antigravity`, `vibe`, `grok`, `cursor`, `qwen` or `opencode` |
| `agents.<name>.bin` | the CLI's own command name | Absolute path to the binary |
-| `agents.<name>.model` | `claude-sonnet-5` for Claude, else the CLI's default | Passed as `--model`; the agent picker's model select writes it |
+| `agents.<name>.model` | `sonnet` for Claude, else the CLI's default | Passed as `--model`; the agent picker's model select writes it. One starting with a dash or holding a space is ignored |
| `agents.<name>.effort` | unset | That CLI's reasoning-effort flag; an unaccepted value is dropped |
+Which models the select offers is not configured: Codex, Antigravity, Grok Build and Cursor CLI are
+asked for their own list, the rest offer a short one Browsentic ships.
+
Full detail, including the Antigravity permission rule: [Choosing an agent](agents.md).
## Runs
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index c92a901..38268d2 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -54,6 +54,7 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d
| `AGENT_NEEDS_PERMISSION` | Antigravity has no rule allowing Browsentic's MCP tools | Press the button in the popup, or `browsentic agent fix antigravity` |
| `AGENT_NEEDS_PERMISSION` for Grok Build | It is not signed in | `grok login`, or set `XAI_API_KEY` |
| "does not understand the flags Browsentic uses" | The agent CLI is too old | Update it |
+| The model select says *built-in list*, with a reason | Browsentic could not read that CLI's own model list — usually it is signed out | Sign the CLI in, then **Recheck**; `browsentic agent models <name> --refresh` shows the reason in full |
| Mistral Vibe fails with *has no API key* | Vibe was never set up, or its key lives only in a shell the daemon was not started from | `vibe --setup`, which stores it in `~/.vibe/.env` |
| Antigravity answers but never touches the page | Its permission rule was removed | `browsentic agent` — it reports *needs setup* again |
| Codex fails with "not logged in" | The daemon inherits no session | `codex login`, then retry |
diff --git a/docs/internals/state.md b/docs/internals/state.md
index 2ef88c5..7291bb7 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -10,6 +10,7 @@ Nothing lives in the repository.
├── auth.json 0600 outstanding pairing code, session keys per browser
├── config.json optional, hand-written
├── approvals.json 0600 "always on this site" grants, one action + host per entry
+├── models.json 0600 each agent CLI's own model list, as last read
├── daemon.log run starts, routed skills, every tool call and its outcome
├── skills/ hand-written skill overrides
├── cli/ macOS app only: the command, the daemon, bundled skills, the extension payload
@@ -30,6 +31,7 @@ Nothing lives in the repository.
| `auth.json` | Pairing | Session keys are per browser profile, keyed by its install id, and survive restarts. Cleared by `browsentic revoke` |
| `config.json` | You, and the agent picker | Re-read before every run — no restart needed. [Reference](../guide/configuration.md) |
| `approvals.json` | **Always on ‹host›** | One action + host per entry. Only short-circuits a `confirm` |
+| `models.json` | The daemon, reading each agent CLI's model list | A cache: deleting it only means the lists are read again. A failed read keeps the last list that read cleanly |
| `cli/`, `bin/`, `runtime/` | [Browsentic.app](../guide/mac-app.md) | Replaced whole on every app update. `cli/.browsentic-app.json` is what makes `installKind()` answer `app`, which turns the npm self-update off |
| `daemon.log` | The daemon | `browsentic logs`. Local [instant commands](../guide/features/instant-commands.md) never appear here, by design |