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: running a saved tool on every visit — the switch, Allow User Scripts, the in-page scope check, and what to do when one does not run
Shahriar67ea4432c313
diff --git a/docs/guide/features/page-actions.md b/docs/guide/features/page-actions.mdindex 409f26c..865c1d1 100644--- a/docs/guide/features/page-actions.md+++ b/docs/guide/features/page-actions.md@@ -108,6 +108,29 @@ action, so no MCP client can call one.Type `/remove-tools` for the list, with a cross beside each. Removing one deletes the code from thebrowser and the note from the daemon together.+### Running one on every visit++The same prompt has a switch that starts off: **Also run it on every visit to youtube.com/watch**.+Turn it on and the tool runs by itself each time you arrive in its scope, with nothing to type. That+covers a page load, and a site that never reloads (YouTube, Gmail) moving you there from elsewhere on+it. Moving between two pages inside the scope is not a new arrival. It runs once the page has loaded+and its content has stopped changing, waiting at most three seconds, because that is the state you+watched it work in. `/remove-tools` has the same switch beside each tool, to turn it off again or+to turn it on for a tool you kept earlier.++It is the code you approved, run in the page's own world, and nothing else. Chrome injects it as a+user script, so there is no debugging bar, DevTools can stay open, and it keeps running after the+browser restarts. The daemon's note about the tool says it runs on every visit, so the agent knows+its effect is usually already on the page. A tool that throws on some visit leaves a line in the page's+console, starting `Browsentic:`, and the page carries on.++**Chrome asks for one switch of its own first.** Open `chrome://extensions`, then Browsentic's+**Details**, and turn on **Allow User Scripts**. Chrome before 138 uses Developer mode instead,+which loading Browsentic unpacked already turned on. Until Chrome allows it, the panel says so and+offers to open that page. The tool remembers that it should run on every visit. It starts within a+couple of seconds of Chrome allowing it, or within a minute if the side panel is closed. Like live+tools themselves, this is Chrome-only.+## Everything else| Group | Tools | See |diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex 3ca33b9..77b2692 100644--- a/docs/guide/troubleshooting.md+++ b/docs/guide/troubleshooting.md@@ -103,6 +103,8 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| `DEBUGGER_UNAVAILABLE` | DevTools is open on that tab | Close DevTools, or use `page_clickElement` instead of `page_trustedClick` || `RUN_IN_PROGRESS` | One instruction at a time per tab | Cancel the running one, or use another tab || `TAB_IN_USE` | That tab belongs to another Browsentic conversation | Switch to it from the Sessions strip |+| A tool set to run on every visit never runs | Chrome keeps user scripts off until you allow them for the extension | `chrome://extensions` → Browsentic → **Details** → **Allow User Scripts**. See [Running one on every visit](features/page-actions.md#running-one-on-every-visit) |+| A tool set to run on every visit ran but changed nothing | It ran before the site had drawn what it changes, or the site changed its markup | The page's console has a `Browsentic:` line if it threw. Run it with `/` to check it still works, and make a new one with the Live tool switch if it does not |## Behaviour that looks wrong but is notdiff --git a/docs/internals/extension.md b/docs/internals/extension.mdindex 6cecefd..8120eb5 100644--- a/docs/internals/extension.md+++ b/docs/internals/extension.md@@ -54,8 +54,9 @@ a `browser_specific_settings.gecko` block the Chrome build has no use for:behind whichever agent CLI the user runs.- **`strict_min_version: 140.0`** — the first Firefox that understands the data-collection key.-Three permissions are filtered out of that build, `sidePanel`, `debugger` and `offscreen`: Firefox has-none of them, and AMO's validator flags each name it does not know. The Firefox sidebar is `sidebar_action`, which WXT+Four permissions are filtered out of that build, `sidePanel`, `debugger`, `offscreen` and+`userScripts`: Firefox's Manifest V2 build has no use for any of them, and AMO's validator flags each+name it does not know. The Firefox sidebar is `sidebar_action`, which WXTderives from the same entrypoint, and the nine tools that need the debugger are left off the list aFirefox build offers (see [Background vs content script](#background-vs-content-script)).@@ -386,6 +387,33 @@ only; **Always on ‹site›** stays in the panel.`~/.browsentic/stopped` behind, and while it is there the host starts nothing; the next daemon tostart, by any other path, removes it.+## Saved tools that run on every visit++A saved tool keeps its code in `storage.local` under `browsentic/savedTools`, and `autoRun` on its+record says whether it should run by itself. That flag is the truth. `auto-run.ts` mirrors it into+Chrome's `userScripts` API, one registration per tool with the id `browsentic-tool-<id>`, in the+`MAIN` world at `document_idle`. The mirror is brought back into line whenever the list changes+(`storage.local.onChanged`), whenever the worker starts, and on the one-minute `browsentic/autoRun`+alarm. It compares code and match patterns and re-registers only what differs.++The `debugger` path that `/` uses would be wrong here. It shows a bar on every attach, fails with+DevTools open, and would have to be driven on each navigation from the worker. A user script is+injected by the browser itself, is exempt from the page's CSP, and outlives a restart. The cost is+Chrome's own per-extension **Allow User Scripts** switch (Developer mode before Chrome 138), which no+API can flip. Until it is on, `chrome.userScripts` is undefined, and `autoRunReady()` turns that+into the `autoRunReady` flag on the run port's `tools` message. Turning it on raises no event and+does not restart the extension; the API just appears in the running worker. So while the panel+shows a tool waiting on it, the panel sends `listTools` every two seconds, which reconciles first.+The alarm covers a closed panel.++The registration matches the whole host, on any port. Scope is decided inside the page by the rule+`/` applies: the exact origin, then the slug of the first path segment. That keeps it right on+single-page sites. There, arriving at `/watch` is a history entry and not a load, so the script also+listens to the Navigation API's `currententrychange`. It runs the entry point on each arrival into+scope, not on each move within it, once `load` has fired and the DOM has gone 400 ms without a+mutation (3 s at most). The approved code is wrapped the way the installer wraps it, and it is+evaluated once per document.+---## Nextdiff --git a/docs/internals/state.md b/docs/internals/state.mdindex dcef3dc..e463baa 100644--- a/docs/internals/state.md+++ b/docs/internals/state.md@@ -57,6 +57,10 @@ after two hours and emptied by the browser on restart. The daemon never receives**Recordings** stay in the extension's own storage, not on disk. Removing the extension removes them.+**Saved tools** keep their code in the extension's `storage.local` under `browsentic/savedTools`; the+daemon gets only a markdown note. A tool set to run on every visit is also registered with Chrome as+a user script, rebuilt from that list whenever it changes, so removing a tool removes both.+**Attached files** stay there too: the bytes under `browsentic:file:<id>`, and the index under`browsentic:files`, where each entry records the conversation it belongs to, the file analyst'sreport and the agent session that report was handed to. A conversation's files are deleted when it