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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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.mdindex 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 instructiagents, changing the model keeps the conversation being held open — every CLI resumes a sessionunder 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:```shbrowsentic agent # what is installed, and what runs the side panelbrowsentic agent codex # switchbrowsentic 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.mdindex 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).## Runsdiff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex 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.mdindex 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 |