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): Cursor CLI as measured — the per-turn approval, the tool lookup, the 60-second call, the 40,000-byte result and the plugin servers
Shahriare7b4b5c2d0b1
diff --git a/docs/guide/agents.md b/docs/guide/agents.mdindex 3f58a3a..658c8ab 100644--- a/docs/guide/agents.md+++ b/docs/guide/agents.md@@ -77,11 +77,12 @@ exactly what each flag buys.too old to understand them fails the run with an explicit "update it" message rather than runninguncontained.-### Follow-up messages, on Claude Code and Codex+### Follow-up messages, on Claude Code, Codex and Cursor-Both keep the system prompt a conversation began with. Claude Code records it on the first request-and sends that record on every resume (its `--system-prompt-snapshot`, on by default), and Codex does-the same with its developer instructions. A later message that changes what the agent should know —+All three keep the system prompt a conversation began with. Claude Code records it on the first+request and sends that record on every resume (its `--system-prompt-snapshot`, on by default), Codex+does the same with its developer instructions, and Cursor answers a resumed turn from the `AGENTS.md`+the conversation started with. A later message that changes what the agent should know —an element picked with A-Eye, a skill attached from the picker, a different skill for the job, notesfor the site you have moved to — would otherwise never reach it.@@ -186,19 +187,36 @@ rate-limited before the model answered. Expect rough edges, and please report th### Cursor CLI is in beta-Browsentic's Cursor runner was checked against `cursor-agent 2026.09.18-9a7762b`: every flag it-passes is accepted, a real turn was read back from its stream, and the deny rules were measured-refusing a shell command in a headless run. What has not been through it yet is a whole-conversation in the side panel — the browser tools reaching a page, and a follow-up turn resuming.-Expect rough edges there, and please report them.+Browsentic's Cursor runner was measured against `cursor-agent 2026.09.18-9a7762b` through its own+plan: the browser tools reaching the model, a picture, a long result, a call that runs past a+minute, a resumed turn, its containment, and a one-shot reading a PNG and a PDF.- **Sign in first.** Run `cursor-agent login`, or set `CURSOR_API_KEY`. Until then a run fails with*Authentication required*.-- **Your own Cursor MCP servers are denied by name.** A project config does not replace the global- `~/.cursor/mcp.json`, so every server you configured for Cursor itself would otherwise load- beside Browsentic's — including your own `browsentic` entry, which reaches the browser without a- run's approval gate. Browsentic reads that file and denies each of them for the run. It never- writes to it.+- **Each turn approves the run's own MCP server.** Cursor starts a project's MCP server only once it+ is approved, and an approval covers that exact configuration, which names the run. So before each+ turn Browsentic runs `cursor-agent mcp enable browsentic` in the run's folder — that one server,+ never `--approve-mcps`, which would approve every server you have. Each adds a line to that+ folder's `mcp-approvals.json` under `~/.cursor/projects`.+- **The model looks a tool up before its first call.** Cursor shows the model a tool's schema only+ when it asks for it, so the first browser action of a conversation takes one step more than on+ Claude Code; the run's prompt has it look up everything the job needs at once.+- **Cursor gives up on a tool call after 60 seconds.** An approval you have not answered by then+ stays on screen: the agent is told you have not decided yet and asks again, under the same card,+ until you do. Anything else it does takes the request down, and an answer after that does+ nothing. Waits inside a call — a monitor, a pick, a captcha, a download — are cut to fit, and+ picked up again with the next call.+- **Text over 40,000 bytes never reaches the model.** Cursor would put a longer result in a file the+ run is not allowed to read, so Browsentic refuses it instead (`RESULT_TOO_LARGE`) and the model+ asks for the page a piece at a time. A long text read is split into pieces that fit.+- **No context count.** Cursor reports tokens added up over every request in a turn, so the context+ card shows none rather than a wrong one.+- **Your own Cursor MCP servers, and every plugin's, are denied.** A project config does not replace+ the global `~/.cursor/mcp.json`, so every server you configured for Cursor itself would otherwise+ load beside Browsentic's — including your own `browsentic` entry, which reaches the browser+ without a run's approval gate. Browsentic reads that file and denies each of them for the run,+ and denies every plugin's server, `plugin-*`, as one. It never writes to that file. If a server it+ denied answers a call anyway, the run is stopped.- **Reasoning effort goes in the model id.** Cursor has no effort flag; it takes bracket overridesinstead, so set `agents.cursor.model` to something like `claude-opus-4-8[effort=high]`.- **On Windows, only the deny rules apply.** Cursor's kernel sandbox is macOS and Linux only.diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex 77b2692..34ba0f6 100644--- a/docs/guide/troubleshooting.md+++ b/docs/guide/troubleshooting.md@@ -76,7 +76,10 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| Mistral Vibe: every action on a follow-up turn fails with `RUN_INACTIVE` | Vibe re-reads a resumed session from the folder it began in, and an older Browsentic wrote each turn to a folder of its own | Update Browsentic, then start a new conversation: one begun before the update keeps its first folder || Grok Build sits silent for minutes, then fails with *xAI did not answer* | The Grok account is rate-limited, as a free one is; Grok retries quietly before giving up | Wait, or upgrade the account || Cursor CLI fails with *Authentication required* | The daemon inherits no session | `cursor-agent login`, or set `CURSOR_API_KEY` |-| Cursor CLI reaches an MCP server you did not expect | A project `.cursor/mcp.json` does not replace your global one, so every server you gave Cursor loads too | Browsentic denies each by name for the run; if one still answers, update Browsentic and report it |+| Cursor CLI answers without ever touching the page, or searches and greps until *Agent Looping Detected* | The run's MCP server was never approved, so Cursor gave the model no browser tools; an older Browsentic did not approve it | Update Browsentic: each turn now approves its own server with `cursor-agent mcp enable browsentic` |+| Cursor CLI fails with *could not be set up for this turn* | `cursor-agent mcp enable browsentic` failed in the run's folder | Run `cursor-agent update`; the message carries what Cursor printed |+| Cursor CLI asks for the same approval again after a minute | Cursor abandons a tool call at 60 s, so an unanswered approval is handed back and the agent calls again under the same card | Nothing to do — answer the card when you are ready |+| Cursor CLI reaches an MCP server you did not expect | A project `.cursor/mcp.json` does not replace your global one, so every server you gave Cursor loads too, as does every plugin's | Browsentic denies each by name for the run, and plugin servers as one; if one still answers, the run is stopped (`AGENT_UNSAFE`) — update Browsentic and report it || Cursor CLI is less fenced off on Windows | Cursor's kernel sandbox has no Windows backend | Nothing to do — the deny rules still apply; treat a Windows run as `host`-class || Windows: `AGENT_UNUSABLE`, *a batch file Browsentic cannot see through* | The agent's command is a batch file that is not an npm or pnpm shim, and Browsentic never runs one through `cmd.exe` | Set `agents.<name>.bin` to the `.exe` it runs || Windows: *This turn is too long for Windows to start* | Codex's `exec` fallback, Qwen Code and Grok Build pass the prompt as an argument, and Windows caps a command line at 32,767 characters | Start a new conversation, or leave out long site notes, attached files or fetched data. Claude Code is not affected |diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.mdindex cf32449..fc8396e 100644--- a/docs/internals/agent-runs.md+++ b/docs/internals/agent-runs.md@@ -97,13 +97,15 @@ Every runner is given the same five things, by whichever mechanism its CLI suppo| | Claude Code | Codex | Antigravity | Mistral Vibe | Grok Build | Cursor CLI | Qwen Code | OpenCode || --- | --- | --- | --- | --- | --- | --- | --- | --- || Run | `claude -p --output-format stream-json`, the message on stdin | `codex app-server`, held over stdin for the turn; `codex exec --json` when it is refused, when `agents.codex.transport` is `"exec"`, and for one-shots | `agy -p --output-format stream-json` | `vibe --prompt … --output streaming --trust --agent ask` | `grok -p --output-format streaming-json` | `cursor-agent -p --output-format stream-json --stream-partial-output` | `qwen -p --output-format stream-json --include-partial-messages` | `opencode run --format json --pure --agent browsentic-contained` |-| MCP server | `--mcp-config` + `--strict-mcp-config` | none: the tools go to `thread/start` as `dynamicTools`, and each of the user's servers is switched off in the thread's config. `exec`: `-c mcp_servers.browsentic.*` under `--ignore-user-config`, with `default_tools_approval_mode="approve"` — headless Codex refuses any MCP call it would have prompted for | `.agents/mcp_config.json` in its cwd | `.vibe/config.toml` in a folder per conversation, every tool granted by name | `.grok/config.toml` in its cwd, loaded with `GROK_FOLDER_TRUST=0`, and approved with `--allow MCPTool(browsentic__*)` | `.cursor/mcp.json` in a folder per conversation, allowed as `Mcp(browsentic:*)` with every other server denied by name | `--mcp-config` + `--allowed-mcp-server-names`, under `--safe-mode`, which drops the ones on disk | `mcp.browsentic` in `OPENCODE_CONFIG_CONTENT`, each tool allowed by name on the run's own agent |-| System prompt | `--append-system-prompt-file`, a file per run, kept from the first turn ([below](#a-prompt-the-session-keeps)) | `developerInstructions` on `thread/start` (`-c developer_instructions` on `exec`), kept from the first turn | `AGENTS.md` in its cwd | `AGENTS.md` beside its config | `--rules` | `AGENTS.md` in its cwd | `--append-system-prompt` | a file in a folder per conversation, named in the config's `instructions` — never the config itself, which OpenCode expands `{file:…}` in |+| MCP server | `--mcp-config` + `--strict-mcp-config` | none: the tools go to `thread/start` as `dynamicTools`, and each of the user's servers is switched off in the thread's config. `exec`: `-c mcp_servers.browsentic.*` under `--ignore-user-config`, with `default_tools_approval_mode="approve"` — headless Codex refuses any MCP call it would have prompted for | `.agents/mcp_config.json` in its cwd | `.vibe/config.toml` in a folder per conversation, every tool granted by name | `.grok/config.toml` in its cwd, loaded with `GROK_FOLDER_TRUST=0`, and approved with `--allow MCPTool(browsentic__*)` | `.cursor/mcp.json` in a folder per conversation, approved each turn with `cursor-agent mcp enable browsentic` (a set-up step the plan carries), allowed as `Mcp(browsentic:*)` with every other server denied by name and every plugin's as `Mcp(plugin-*:*)` | `--mcp-config` + `--allowed-mcp-server-names`, under `--safe-mode`, which drops the ones on disk | `mcp.browsentic` in `OPENCODE_CONFIG_CONTENT`, each tool allowed by name on the run's own agent |+| System prompt | `--append-system-prompt-file`, a file per run, kept from the first turn ([below](#a-prompt-the-session-keeps)) | `developerInstructions` on `thread/start` (`-c developer_instructions` on `exec`), kept from the first turn | `AGENTS.md` in its cwd | `AGENTS.md` beside its config | `--rules` | `AGENTS.md` in its cwd, kept from the first turn | `--append-system-prompt` | a file in a folder per conversation, named in the config's `instructions` — never the config itself, which OpenCode expands `{file:…}` in || Follow-up turns | `--resume <session>` | `thread/resume` (`exec resume <thread>`); either resumes a thread the other began | `--conversation <id>` | `--resume <session>`, re-read from the folder the session began in | `--session-id <uuid>` names it, `--resume <uuid>` continues it, in a folder named after it | `--resume <session>` | `--session-id <uuid>` names it, `--resume <uuid>` continues it | `--session <id>`, from a session store of Browsentic's own (`OPENCODE_DB`) || Kept off the machine by | `--allowedTools` + `--disallowedTools` | the user's MCP servers off (`--ignore-user-config` on `exec`), `-c sandbox_mode="read-only"`, `-c approval_policy="never"`, `-c features.shell_tool=false`, `-c features.view_image=false`, `-c features.multi_agent=false` | its own permission rules | `--enabled-tools`, which is an allowlist | `--tools`, `--permission-mode dontAsk`, `--deny`, `--sandbox workspace` | deny rules in `.cursor/cli.json`, plus `--sandbox enabled` | `--safe-mode`, `--exclude-tools`, `--approval-mode default` | an agent whose permission opens on `"*": "deny"`, `--pure`, `OPENCODE_DISABLE_PROJECT_CONFIG`, `OPENCODE_DISABLE_SHARE` |-**Two CLIs do not put the browser tools in the model's list, and both are told so in the prompt.**-Grok reaches MCP tools only through two meta-tools, `search_tool` and `use_tool`, under a+**Three CLIs do not put the browser tools in the model's list, and each is told so in the prompt.**+Cursor hands the model a tool's schema only through its own `GetMcpTools`, by pattern or by name, so+its `AGENTS.md` ends with a section saying to look up every tool the job needs in one step. Grok+reaches MCP tools only through two meta-tools, `search_tool` and `use_tool`, under a`browsentic__` prefix. Codex on its `exec` fallback defers them behind its own `tool_search`, and a code-mode model(`tool_mode: "code_mode_only"` in its model catalog) reaches them only from inside `exec`, as`tools.mcp__browsentic__*`, where an image reaches the model only if the script passes it to@@ -115,6 +117,27 @@ Codex also cuts any tool result at 10,000 tokens by default, which its model cat`// @exec: {"max_output_tokens": 25000}`, and only the prompt can ask for that, so it does. It alsoasks for page reads in pieces.+**A CLI with limits on a tool call declares them** (`Runner.limits`), and the daemon works inside+them rather than the run finding them out. Cursor abandons a call at 60 s — the MCP SDK's default+request timeout, which it never overrides — and puts text over 40,000 bytes in a file the run cannot+read (measured on 2026.09.18). So for its runs:++- an approval still unanswered 10 s before the limit is *parked*: the call returns `APPROVAL_PENDING`+ with no `toolResult`, so the card stays up, and the same action with the same input rejoins it+ under the same row. Any other call, the run ending, or Stop withdraws it, and a late answer does+ nothing;+- a wait inside a call (`page_awaitMonitor`, `page_pickElement`, `page_solveCaptcha`,+ `page_captureDownload`, and any `timeoutMs` on `page_runCode`, `page_callSiteTool` or+ `page_waitForElement`) is cut to what is left of the call;+- the run's MCP server is started with `BROWSENTIC_RESULT_BYTES`, refuses a result whose text is+ over it with `RESULT_TOO_LARGE` rather than cutting it, and asks `page_extractText` for groups of a+ quarter that many characters.++Separately, for every CLI, **a call its client abandons withdraws its approval.** The MCP server+passes the request's cancel signal to the bridge, which sends `{ op: 'cancel', id }` on the control+socket, and the daemon aborts that invoke; a tool server whose socket closes mid-call does the same+for everything it had in flight. Before, a late Allow ran the action after the model had moved on.+**A CLI that re-reads its own folder gets one per conversation, not one per run.** Vibe restores aresumed session from the folder it began in, whatever folder it is started in now, so a folder perrun left every follow-up turn calling the browser with the first turn's `BROWSENTIC_AGENT_RUN` —diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.mdindex 606e6fb..6ffda2b 100644--- a/docs/internals/guardrails.md+++ b/docs/internals/guardrails.md@@ -354,7 +354,7 @@ type LocalTools = 'allowlist' | 'sandbox' | 'host'| **Mistral Vibe** | `allowlist` | `--enabled-tools` is the whole of what loads: Browsentic's MCP tools, plus web search and fetch on a research run. The shell and file tools never exist in the run, and `--auto-approve` is a forbidden flag || **Grok Build** | `allowlist` | A per-run built-in tool list, `--permission-mode dontAsk`, deny rules, and a kernel sandbox for writes. Reads are closed by the tool list and a `Read` deny rather than the sandbox, and MCP servers the user set up in Grok itself still load || **Qwen Code** | `allowlist` | `--allowed-tools mcp__browsentic` is what a run may call without being asked, and a headless turn refuses everything it would otherwise have prompted for. `--safe-mode` is what makes the rest hold: it drops the user's hooks, extensions, bundled skills, `settings.json` MCP servers, `.mcp.json` and permission rules, while keeping `--mcp-config` — an explicit per-invocation argument rather than ambient state. Its cost is that it also **silently ignores `--core-tools`**, the fail-closed allowlist over Qwen's twenty-one core tools, so the built-ins are closed with `--exclude-tools` deny rules instead. A deny list cannot be fail-closed, so the `init` line is read back: it names every tool and MCP server that actually registered, and the reader ends the run with `AGENT_UNSAFE` on anything Browsentic did not ask for, before the model has spoken |-| **Cursor CLI** | `allowlist` | Deny rules in a project `.cursor/cli.json`, where **a deny beats every allow** — including the user's own. Measured against 2026.09.18: a headless run asked to `echo` a marker got `permissionDenied`, twice, and gave up. `--sandbox enabled` is asked for as well but not depended on, and it has no Windows backend. This is the first runner whose containment lives in a file rather than in argv, which is why `vetPlan` checks file *content* and not only that the file was written. `--trust` is **required**, not forbidden: headless Cursor refuses to start in a folder nobody trusted, and the folder is one Browsentic created and wrote every file in — it grants no tool permission of its own |+| **Cursor CLI** | `allowlist` | Deny rules in a project `.cursor/cli.json`, where **a deny beats every allow** — including the user's own. Measured against 2026.09.18: a headless run asked to `echo` a marker got `permissionDenied`, twice, and gave up. `--sandbox enabled` is asked for as well but not depended on, and it has no Windows backend. This is the first runner whose containment lives in a file rather than in argv, which is why `vetPlan` checks file *content* and not only that the file was written. `--trust` is **required**, not forbidden: headless Cursor refuses to start in a folder nobody trusted, and the folder is one Browsentic created and wrote every file in — it grants no tool permission of its own. The project's MCP server starts only once approved, keyed to its exact config, so each turn's plan carries one set-up step, `cursor-agent mcp enable browsentic`, run in its folder before the turn; `vetPlan` allows that step and no other, for a run and never a task, and `--approve-mcps` — which approves every server the user has — stays forbidden. Every plugin's MCP server loads in every run under `plugin-<plugin>-<server>`, so `Mcp(plugin-*:*)` is denied beside the user's own servers by name, and an answer from any server but `browsentic` ends the run with `AGENT_UNSAFE` || **OpenCode** | `allowlist` | The run is an agent the config defines, whose permission ruleset opens on `"*": "deny"` and then allows each browser tool by name. OpenCode applies the last rule that matches and puts an agent's rules after the user's, so every other tool — built-in, custom, another MCP server's, or one a later release adds — is denied, and a tool denied outright is never offered to the model. `--pure` keeps plugins out, which run inside OpenCode and can answer its permission prompts. MCP servers the user set up in OpenCode itself still start, with their tools hidden |**Windows is less measured.** Cursor's kernel sandbox has no Windows backend, so only its deny rulesdiff --git a/docs/reference/errors.md b/docs/reference/errors.mdindex 9c9c808..91b0a5c 100644--- a/docs/reference/errors.md+++ b/docs/reference/errors.md@@ -60,6 +60,9 @@ repeatedly: failures carry the *fix* in the message, and a failed tool call neve| `TAB_IN_USE` | Extension | That tab belongs to another Browsentic conversation || `RUN_INACTIVE` | AgentSession | The run was cancelled while a tool call was in flight || `APPROVAL_TIMEOUT` | AgentSession | A scheduled run asked for approval and nobody answered within ten minutes, so the action was declined. The agent is told to stop and say what it was about to do |+| `APPROVAL_PENDING` | AgentSession | The user has not answered an approval yet, and the agent's CLI would abandon the call before they do (Cursor CLI, at 60 s). The request stays on screen: make the **same call again, with the same input**, to keep waiting. Any other call withdraws it |+| `RESULT_TOO_LARGE` | MCP server | The call went through, but its result is longer than the agent's CLI passes to its model (Cursor CLI: 40,000 bytes). Do not repeat an action for its result; ask for less — `page_extractText` with a smaller `maxLength` and its cursor, `page_getPageInfo` with a smaller `maxPerKind`, or a `target` |+| `CANCELLED` | AgentSession | The call was abandoned before the user answered its approval, so the request was taken down and a late answer does nothing || `SKILL_UNKNOWN` | AgentSession | The attached agent skill's id no longer resolves — the file moved, changed agents, or outgrew the size cap. Reopen the `/` picker and choose again |## Scheduled tasks@@ -77,7 +80,7 @@ repeatedly: failures carry the *fix* in the message, and a failed tool call neve| `AGENT_MISSING` | Runner | The chosen agent's binary is not on the *daemon's* `PATH`. Set `agents.<name>.bin` to an absolute path || `AGENT_NEEDS_PERMISSION` | Runner | Antigravity has no rule allowing Browsentic's MCP tools (`browsentic agent fix antigravity`), Grok Build or Cursor CLI is not signed in (`grok login`, `cursor-agent login`), Qwen Code has no model provider configured (`qwen`, then `/auth`), or OpenCode is signed in to no provider (`opencode auth login`) || `AGENT_UNUSABLE` | Runner | The CLI is present but cannot run — usually too old for the flags Browsentic passes. On Windows, also a batch file that is not an npm or pnpm shim: set `agents.<name>.bin` to the program it runs |-| `AGENT_UNSAFE` | Runner | The run was stopped before the agent could act on the machine: its plan had lost its containment, which is a bug in Browsentic, or the CLI itself said it had not applied it — Grok Build offering tools Browsentic never asks for, Qwen Code reporting a denied tool or a second MCP server as registered, OpenCode reporting that a tool outside the browser ran, or Codex running a shell command or changing a file with both switched off. Update both, and report it |+| `AGENT_UNSAFE` | Runner | The run was stopped before the agent could act on the machine: its plan had lost its containment, which is a bug in Browsentic, or the CLI itself said it had not applied it — Grok Build offering tools Browsentic never asks for, Qwen Code reporting a denied tool or a second MCP server as registered, OpenCode reporting that a tool outside the browser ran, Codex running a shell command or changing a file with both switched off, or Cursor CLI getting an answer from an MCP server the run denies. Update both, and report it |## Guardrails