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: 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.md
index 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 the
browser 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.md
index 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 not
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index 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 WXT
derives from the same entrypoint, and the nine tools that need the debugger are left off the list a
Firefox 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 to
start, 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.
+
---
## Next
diff --git a/docs/internals/state.md b/docs/internals/state.md
index 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's
report and the agent session that report was handed to. A conversation's files are deleted when it