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: install from the stores — the extension from the Chrome Web Store (Edge too until its listing is out) or the signed Firefox add-on, Browsentic Bridge from the apps or npx, a code entered once; the window that lets the two differ in version, store listings and what each dashboard asks for, the README's three steps with store badges, the npm page, release notes and app screenshots
Shahriar959702ba9470
diff --git a/README.md b/README.mdindex 70aaf45..06c30c5 100644--- a/README.md+++ b/README.md@@ -5,6 +5,8 @@ https://github.com/user-attachments/assets/e9f146d3-cb14-416e-b8d7-68c4e81cbd0d# Browsentic – a completely integrated agentic browser extension<p>+ <a href="https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp"><img src="https://img.shields.io/chrome-web-store/v/npmocgldfflonjjmdadmdefpnfagnjmp?logo=googlechrome&logoColor=white&label=Chrome%20Web%20Store" alt="Chrome Web Store version"></a>+ <a href="https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp"><img src="https://img.shields.io/chrome-web-store/users/npmocgldfflonjjmdadmdefpnfagnjmp?logo=googlechrome&logoColor=white&label=users" alt="Chrome Web Store users"></a><a href="https://www.npmjs.com/package/browsentic"><img src="https://img.shields.io/npm/v/browsentic?logo=npm" alt="npm version"></a><a href="https://www.npmjs.com/package/browsentic"><img src="https://img.shields.io/npm/dm/browsentic?logo=npm" alt="npm downloads"></a><a href="https://github.com/imshaikot/browsentic/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/imshaikot/browsentic/ci.yml?branch=main&label=CI&logo=githubactions&logoColor=white" alt="CI"></a>@@ -25,11 +27,11 @@ Also an optional [MCP server](docs/guide/mcp-clients.md), so any MCP client can<p><strong>Works in</strong><br>- <a href="docs/guide/install.md"><img src="https://browsentic.com/icons/chrome.svg" width="40" height="40" alt="Chrome" title="Chrome"></a> + <a href="https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp"><img src="https://browsentic.com/icons/chrome.svg" width="40" height="40" alt="Chrome" title="Chrome"></a> <a href="docs/guide/install.md#firefox"><img src="https://browsentic.com/icons/firefox.svg" width="40" height="40" alt="Firefox" title="Firefox"></a> - <a href="docs/guide/install.md"><img src="https://browsentic.com/icons/edge.svg" width="40" height="40" alt="Edge" title="Edge"></a> - <a href="docs/guide/install.md"><img src="https://browsentic.com/icons/brave.svg" width="40" height="40" alt="Brave" title="Brave"></a> - <a href="docs/guide/install.md"><img src="https://browsentic.com/icons/arc.svg" width="40" height="40" alt="Arc" title="Arc"></a>+ <a href="docs/guide/install.md#1-add-the-extension"><img src="https://browsentic.com/icons/edge.svg" width="40" height="40" alt="Edge" title="Edge"></a> + <a href="https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp"><img src="https://browsentic.com/icons/brave.svg" width="40" height="40" alt="Brave" title="Brave"></a> + <a href="https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp"><img src="https://browsentic.com/icons/arc.svg" width="40" height="40" alt="Arc" title="Arc"></a></p><p><strong>Runs on</strong><br>@@ -47,25 +49,42 @@ Also an optional [MCP server](docs/guide/mcp-clients.md), so any MCP client can## Quick Start-**Any platform** — with [Node.js](https://nodejs.org) 20 or newer (Windows is [experimental](docs/guide/limits.md#windows-is-experimental)):+Browsentic is your browser's superpower, free and open source. It is two pieces plus the AI you already use:-```sh-npx browsentic setup-```+**1. The extension**, in your browser: from the Chrome Web Store for Chrome, Edge, Brave, Arc, Vivaldi and Opera, or the signed add-on for Firefox.-**macOS** — one line installs [Browsentic.app](docs/guide/mac-app.md), which brings Node and everything else:+<p>+ <a href="https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp"><img src="https://img.shields.io/badge/Chrome%20Web%20Store-Add%20to%20Chrome-4285F4?style=for-the-badge&logo=googlechrome&logoColor=white" alt="Add to Chrome from the Chrome Web Store"></a>+ <a href="https://browsentic.com/download/firefox"><img src="https://img.shields.io/badge/Firefox-Get%20the%20add--on-FF7139?style=for-the-badge&logo=firefoxbrowser&logoColor=white" alt="Get the Firefox add-on"></a>+</p>++**2. Browsentic Bridge**, on your computer. It runs your agent and keeps everything local.++**macOS** — one line installs [the app](docs/guide/mac-app.md), which brings Node and everything else:```shcurl -fsSL https://browsentic.com/install.sh | sh```-**Windows** — one line in PowerShell installs [the Windows app](docs/guide/windows-app.md), which brings Node and everything else ([experimental](docs/guide/limits.md#windows-is-experimental)):+**Windows** — one line in PowerShell installs [the Windows app](docs/guide/windows-app.md) ([experimental](docs/guide/limits.md#windows-is-experimental)):```powershellirm https://browsentic.com/install.ps1 | iex```-Full install and setup guide, Firefox included: **[browsentic.com/docs/guide/install](https://browsentic.com/docs/guide/install/)**+**Any platform** — with [Node.js](https://nodejs.org) 20 or newer:++```sh+npx browsentic@latest setup+```++It asks which browser should get the extension, opens its store page there, and prints a pairing code. The apps do the same from a window.++**3. An agent CLI you're signed in to:** [Claude Code](https://claude.com/claude-code), [Codex](https://developers.openai.com/codex/cli) or [another supported one](docs/guide/agents.md). You probably have one already.++Install 1 and 2 in either order, then click Browsentic in the toolbar and enter the pairing code, once. No API key, no account, no subscription.++Full guide, Firefox and unpacked installs included: **[browsentic.com/docs/guide/install](https://browsentic.com/docs/guide/install/)**## Key Capabilities@@ -105,16 +124,16 @@ Full install and setup guide, Firefox included: **[browsentic.com/docs/guide/ins<summary>The same flow, as text</summary>```-You ──speak or type──> Extension ──local WebSocket──> Daemon ──spawns──> your agent CLI- ▲ (claude │ codex │ agy │ vibe │ grok)- └──────────────── page actions ─────────────────────┘+You ──speak or type──> Extension ──local WebSocket──> Browsentic Bridge ──spawns──> your agent CLI+ ▲ (claude │ codex │ agy │ …)+ └──────────────────── page actions ──────────────────────┘-Any MCP client ──stdio──> browsentic mcp ──> the same daemon ──> the same browser+Any MCP client ──stdio──> browsentic mcp ──> the same Bridge ──> the same browser```</details>-The extension dials out to the daemon, because a Manifest V3 service worker cannot listen for connections. One daemon owns the browser link, so several MCP clients can share one browser. Everything binds to `127.0.0.1`.+The extension dials out to Browsentic Bridge, because a Manifest V3 service worker cannot listen for connections. One Bridge owns the browser link, so several MCP clients can share one browser. Everything binds to `127.0.0.1`.## Resourcesdiff --git a/docs/README.md b/docs/README.mdindex 0200636..7367e34 100644--- a/docs/README.md+++ b/docs/README.md@@ -15,7 +15,7 @@ Start here if you want to run Browsentic on your own machine.| | || --- | --- |-| [Install](guide/install.md) | One command, then load the extension |+| [Install](guide/install.md) | The extension from your browser's store, and Browsentic Bridge on your computer || [Pair](guide/pair.md) | Connect your browser with a single-use code || [First run](guide/first-run.md) | A tour of the side panel and your first instruction || [Features](guide/features/) | One page per capability — what it does and when to reach for it |@@ -45,6 +45,7 @@ How the pieces actually work, for contributors and for anyone integrating.| [Subsystems](internals/subsystems.md) | Monitors, recordings, site maps, files, screenshots || [State on disk](internals/state.md) | What is written where, and at what mode || [Contributing](internals/contributing.md) | Build topology, checks, adding a capability |+| [Store listings](internals/stores.md) | Store IDs, submitting an update, what the dashboards ask for |## Looking something updiff --git a/docs/assets/mac-app/browsers.webp b/docs/assets/mac-app/browsers.webpindex 6d79f9d..7187513 100644Binary files a/docs/assets/mac-app/browsers.webp and b/docs/assets/mac-app/browsers.webp differdiff --git a/docs/assets/mac-app/overview.webp b/docs/assets/mac-app/overview.webpindex 2758bbf..b569181 100644Binary files a/docs/assets/mac-app/overview.webp and b/docs/assets/mac-app/overview.webp differdiff --git a/docs/guide/README.md b/docs/guide/README.mdindex 2b262c7..c5ee23b 100644--- a/docs/guide/README.md+++ b/docs/guide/README.md@@ -7,7 +7,7 @@ Everything you need to run Browsentic on your own machine and your own browser.Three short steps, about five minutes in total. There is no account, no API key and no cloudservice.-1. **[Install](install.md)** — one command, then load the extension. On a Mac or on Windows, an app ([macOS](mac-app.md), [Windows](windows-app.md)) does the same from a window+1. **[Install](install.md)** — the extension from your browser's store, and Browsentic Bridge on your computer: an app on a Mac or on Windows ([macOS](mac-app.md), [Windows](windows-app.md)), or one command2. **[Pair](pair.md)** — connect your browser with a single-use code3. **[First run](first-run.md)** — a tour of the side panel, and your first instructiondiff --git a/docs/guide/agents.md b/docs/guide/agents.mdindex 658c8ab..d8df6d3 100644--- a/docs/guide/agents.md+++ b/docs/guide/agents.md@@ -34,7 +34,7 @@ The other four have no such command, so the select offers a short list BrowsentiCode those are its aliases — `fable`, `opus`, `sonnet`, `haiku` — which it resolves to the newestmodel of each family.-The daemon reads a list in the background and never holds the popup up for one. A list it has read+The Bridge reads a list in the background and never holds the popup up for one. A list it has readis 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@@ -68,7 +68,7 @@ agents cannot resume each other's sessions, so the next instruction starts a fre| Kept off your machine by | a per-run tool allowlist plus an explicit deny list | its shell and image viewer switched off, no MCP server but the browser's, and 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 |All eight get the same system prompt, the same browser tools — over a `browsentic` MCP server pointed-back at the daemon, or for Codex handed to it directly — and the same [approval gate](approvals.md).+back at the Bridge, or for Codex handed to it directly — and the same [approval gate](approvals.md).What differs is how well each one can be fenced off from the rest of your machine — see[internals/guardrails.md § Spawn containment](../internals/guardrails.md#spawn-containment) forexactly what each flag buys.@@ -89,7 +89,7 @@ for the site you have moved to — would otherwise never reach it.So Browsentic carries what changed in the message itself: a short *instructions for this message*section ahead of your words, holding only the parts that differ from what the conversation alreadyhas, and naming any that no longer apply. A message that changes nothing carries nothing extra. After-the daemon restarts it cannot know what a conversation holds, so the first follow-up restates the+the Bridge restarts it cannot know what a conversation holds, so the first follow-up restates thewhole prompt once. The agent's prompt cache is untouched either way, because nothing that came beforechanges.@@ -99,11 +99,11 @@ Codex runs through its **app-server** — the interface its own editor extensionthe length of a turn. Browsentic hands it the browser tools directly, so they are in the model'slist from the first request, rather than as an MCP server whose tools Codex would defer until themodel searched for them. Its replies stream in as they are written, and the context card shows how-full its window is. Each tool call it makes comes back to the daemon and goes through the same gate,+full its window is. Each tool call it makes comes back to the Bridge and goes through the same gate,approvals and timeline as a Claude Code run's.The app-server interface is marked experimental. If a Codex build refuses it, the same turn runs-through `codex exec` instead and later turns go straight there until the daemon restarts; the two+through `codex exec` instead and later turns go straight there until the Bridge restarts; the tworesume each other's conversations. `"transport": "exec"` under `agents.codex` in `config.json`chooses exec outright.@@ -325,7 +325,7 @@ In `~/.browsentic/config.json`:| Key | Default | Effect || --- | --- | --- || `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`. On Windows it may name the `.cmd` npm installed, or the `.exe` itself. |+| `agents.<name>.bin` | the CLI's own command name | Absolute path to the binary. Set this when the Bridge's `PATH` differs from your shell's — the usual cause of `AGENT_MISSING`. On Windows it may name the `.cmd` npm installed, or the `.exe` itself. || `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. |@@ -340,16 +340,16 @@ Claude runner's settings.| Symptom | Fix || --- | --- |-| `AGENT_MISSING` | The daemon's `PATH` differs from your shell's. Set `agents.<name>.bin` to an absolute path. |+| `AGENT_MISSING` | The Bridge's `PATH` differs from your shell's. Set `agents.<name>.bin` to an absolute path. || `AGENT_NEEDS_PERMISSION` | Antigravity has no rule for Browsentic's tools: press the button, or `browsentic agent fix antigravity`. Grok Build is not signed in: run `grok login`. Qwen Code has no model provider: run `qwen` and use `/auth`. OpenCode is signed in to no provider: run `opencode auth login`. |-| Codex: "not logged in" | The daemon inherits no session. Run `codex login`, then retry. |+| Codex: "not logged in" | The Bridge inherits no session. Run `codex login`, then retry. || Codex answers about the page without opening it, or from a web search | Update Browsentic. Codex hides the browser tools until the model searches for them, and an older Browsentic left Codex's own web search switched on, which the model reached for first. || Mistral Vibe: a follow-up turn says *this agent run is no longer active* | Update Browsentic, then start a new conversation. An older one gave each turn its own folder, and Vibe keeps re-reading the first turn's, so a conversation begun before the update stays broken. || "does not understand the flags Browsentic uses" | The CLI is too old. Update it. || Antigravity answers but never touches the page | Its permission rule was removed. `browsentic agent` reports *needs setup* again. || Antigravity: a follow-up turn searches the web, or ends with no answer, instead of reading the page | Update Browsentic, then start a new conversation. An older one gave each turn its own folder, and Antigravity keeps re-reading the first turn's, so every browser call in a later turn was refused as *no longer active*. A conversation begun before the update stays broken. || Grok Build sits silent for minutes, then *xAI did not answer* | The Grok account is rate-limited — a free one usually is. Wait, or upgrade the account. |-| Cursor CLI: *Authentication required* | The daemon inherits no session. Run `cursor-agent login`, or set `CURSOR_API_KEY`, then retry. |+| Cursor CLI: *Authentication required* | The Bridge inherits no session. Run `cursor-agent login`, or set `CURSOR_API_KEY`, then retry. || Cursor CLI on Windows | Cursor's sandbox has no Windows backend, so only the deny rules apply there. The browser still works; the machine is less fenced off than on macOS or Linux. || 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. 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, which Windows caps at 32,767 characters. Start a new conversation, or leave out long site notes and attachments. See [Limits](limits.md#windows-is-experimental). |diff --git a/docs/guide/approvals.md b/docs/guide/approvals.mdindex 7bf26f4..6dbf758 100644--- a/docs/guide/approvals.md+++ b/docs/guide/approvals.md@@ -118,9 +118,9 @@ block "search for X" on an empty tab.### Sites that are never in scope-Scope is a question the daemon answers per run, and config.json can widen it. For a site the agent+Scope is a question the Bridge answers per run, and config.json can widen it. For a site the agentmust never touch at all, use [Blocked sites](features/blocked-sites.md) instead: the extension enforces-that list itself, before any of these rules run, and nothing on the daemon's side can read or change+that list itself, before any of these rules run, and nothing on the Bridge's side can read or changeit. A run started from a blocked tab does not send its address, so it begins unconfined, as from ablank tab — and every action on the blocked site is refused all the same.@@ -149,8 +149,8 @@ be asking about something already answered. What holds it in place is not a promitself, which pins the origin and the path segment it was approved on and re-checks both before itinstalls anything.-The daemon is not in that loop. The code lives in extension storage, the run goes from the side-panel straight to the tab, and the daemon holds only a markdown note that the tool exists. There+The Bridge is not in that loop. The code lives in extension storage, the run goes from the side+panel straight to the tab, and the Bridge holds only a markdown note that the tool exists. Thereis no action for it, so no MCP client can reach it, with or without `unattended`.It does not waive a `deny`. That is why the two live-tool rules deny rather than confirm: a@@ -214,7 +214,7 @@ accident. Hand-editing config.json still works if you genuinely mean it.Credential sealing appears in the list with no switch at all, because there is nothing to turn off:it is what keeps a plaintext password off the socket in the first place.-An agent run cannot use either screen's route to loosen its own rules: the daemon refuses a+An agent run cannot use either screen's route to loosen its own rules: the Bridge refuses asettings change from a connection that has acted for a run, with `BLOCKED`.---diff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex 9fcc85d..a54bf74 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -2,7 +2,7 @@Everything is optional. Browsentic works with no config file at all.-Settings live in `~/.browsentic/config.json`. The daemon re-reads it before every run, so an edit+Settings live in `~/.browsentic/config.json`. The Bridge re-reads it before every run, so an editapplies to the next thing you ask — no restart. It also watches the file, so the extension's settingspage and the Mac app show a hand edit the moment you save it.@@ -95,9 +95,9 @@ Every rule id and what it does, plus the three that the panel shows but will not| --- | --- | --- || `screenshotDir` | `~/browsentic/screenshot` | Where captures taken with `save: true` are written, mode `0600` || `downloadDir` | `~/browsentic/download` | Where files captured with `page_captureDownload` are written, mode `0600` |-| `downloadTtlDays` | `14` | How long a captured download is kept before the daemon sweeps it. Fractions allowed — `0.5` is twelve hours |+| `downloadTtlDays` | `14` | How long a captured download is kept before the Bridge sweeps it. Fractions allowed — `0.5` is twelve hours || `skillsDir` | `~/browsentic/skills` | Where panel uploads and generated site maps live |-| `extensionDir` | `~/browsentic/extension/chrome-mv3` | Where `browsentic setup` installed the unpacked extension. Written for you by `setup --dir`, and read back by `update` so it refreshes the copy the browser actually loaded. Changing it by hand means loading the new folder in the browser again, because the extension ID follows the path |+| `extensionDir` | `~/browsentic/extension/chrome-mv3` | Where `browsentic setup --unpacked` writes the unpacked extension. Written for you by `--dir`, and read back by `update` so it refreshes the copy the browser actually loaded. Changing it by hand means loading the new folder in the browser again, because the extension ID follows the path |## Site mapping@@ -128,7 +128,7 @@ offers, so the preview is the thing itself.One theme serves every paired browser: picking one anywhere repaints the panel, the popup and thesettings page in all of them. A browser that has never been paired keeps its choice to itself and-hands it to the daemon when it first connects; one picked while the daemon is unreachable is handed+hands it to the Bridge when it first connects; one picked while the Bridge is unreachable is handedover at the next connect. The Mac app's own window keeps its separate System / Light / Dark setting.### The Extension section@@ -174,7 +174,7 @@ and every field in it is optional:| `instructions` | 4,000 characters | Kept on every task |An entry that breaks a limit, or a key the page does not know, is left out rather than cut short —-the daemon logs that it did. What the agent is told, and what is refused, is in+the Bridge logs that it did. What the agent is told, and what is refused, is in[Profile](features/profile.md).---diff --git a/docs/guide/features/blocked-sites.md b/docs/guide/features/blocked-sites.mdindex 8218f5c..da4ec85 100644--- a/docs/guide/features/blocked-sites.md+++ b/docs/guide/features/blocked-sites.md@@ -50,13 +50,13 @@ shows a banner while the active tab is blocked; the agent can still work in othe## Why nothing can override it-The list lives in this browser's extension storage and nowhere else. No message from the daemon can+The list lives in this browser's extension storage and nowhere else. No message from the Bridge canread or write it, and the extension checks it before every page action, inside the browser — so neitherthe agent, an MCP client, nor anything that edits `~/.browsentic/config.json` can loosen it. Thecontent script in the page checks it a second time, and the agent cannot steer a tab onto the settingspage to edit it: page actions refuse anything that is not an http(s) page.-That makes it different from [approvals](../approvals.md), which the daemon applies and you can tune+That makes it different from [approvals](../approvals.md), which the Bridge applies and you can tuneper run: a blocked site is not a question the agent can ask.## Edgesdiff --git a/docs/guide/features/captcha.md b/docs/guide/features/captcha.mdindex 9c167b4..ff2b417 100644--- a/docs/guide/features/captcha.md+++ b/docs/guide/features/captcha.md@@ -63,7 +63,7 @@ Chrome only. It shows the debugger bar while it runs.## Image challenges-The extension photographs the challenge and hands it to the daemon, which starts a one-shot+The extension photographs the challenge and hands it to the Bridge, which starts a one-shotsession of your configured agent to look at that single picture. The session answers and isstopped at once; nothing carries over to the next round. The extension then clicks the answerwith real pointer movement, presses the challenge's own button, and photographs whatever comesdiff --git a/docs/guide/features/instant-commands.md b/docs/guide/features/instant-commands.mdindex 7467a40..a077af9 100644--- a/docs/guide/features/instant-commands.md+++ b/docs/guide/features/instant-commands.md@@ -53,7 +53,7 @@ A local command that runs and **fails** also escalates, rather than reporting th## Two things this explains-**Local commands leave no trace in `browsentic logs`.** They never reach the daemon. That is+**Local commands leave no trace in `browsentic logs`.** They never reach the Bridge. That isexpected, not a bug — the ⚡ is where they show up.**Explaining any single routing decision:**diff --git a/docs/guide/features/monitoring.md b/docs/guide/features/monitoring.mdindex 5f21d36..e27af5f 100644--- a/docs/guide/features/monitoring.md+++ b/docs/guide/features/monitoring.md@@ -16,7 +16,7 @@ work elsewhere**. It tracks percent, extrapolates an ETA from the sample historyprogress has stalled, and notifies you on completion.The watch runs in the extension. It needs no further tool calls, and it keeps running even if the-agent finishes, the MCP client disconnects, or the daemon goes away.+agent finishes, the MCP client disconnects, or the Bridge goes away.---diff --git a/docs/guide/features/page-actions.md b/docs/guide/features/page-actions.mdindex 865c1d1..3524485 100644--- a/docs/guide/features/page-actions.md+++ b/docs/guide/features/page-actions.md@@ -101,12 +101,12 @@ Scope is the host plus the first path segment. A tool made on a `/watch` page is`/watch` page and nowhere else on the host, and never on another host.The two halves are stored apart. The JavaScript lives in the extension's own storage and goes-nowhere else; the daemon gets a markdown note that the tool exists and what it does, so the agent+nowhere else; the Bridge gets a markdown note that the tool exists and what it does, so the agentcan point you at it instead of writing the same thing again. Nothing about a saved tool is a pageaction, 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.+browser and the note from the Bridge together.### Running one on every visit@@ -120,13 +120,13 @@ 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 auser 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+browser restarts. The Bridge's note about the tool says it runs on every visit, so the agent knowsits effect is usually already on the page. A tool that throws on some visit leaves a line in the page'sconsole, 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+**Details**, and turn on **Allow User Scripts**. Chrome before 138 uses Developer mode instead, the+switch at the top right of `chrome://extensions`. Until Chrome allows it, the panel says so andoffers to open that page. The tool remembers that it should run on every visit. It starts within acouple of seconds of Chrome allowing it, or within a minute if the side panel is closed. Like livetools themselves, this is Chrome-only.diff --git a/docs/guide/features/profile.md b/docs/guide/features/profile.mdindex 7e162d1..386892e 100644--- a/docs/guide/features/profile.md+++ b/docs/guide/features/profile.md@@ -38,7 +38,7 @@ as two sections:Instructions cannot loosen the handful of rules every run starts with — page text is never aninstruction, nothing is exfiltrated, a declined action stays declined — and cannot make an action skip-its [approval](../approvals.md). Guardrails are enforced by the daemon, not by the prompt, so a rule+its [approval](../approvals.md). Guardrails are enforced by the Bridge, not by the prompt, so a rulethat tried would change nothing but what the agent says.An edit reaches the next run. In a conversation that is already going, the next message carries the@@ -65,8 +65,8 @@ at once. The format is in [Configuration](../configuration.md#profile) if you wo## Edges-- It needs the daemon: the settings page reads and writes the file through it, so the section is empty- while the daemon is offline.+- It needs the Bridge: the settings page reads and writes the file through it, so the section is empty+ while the Bridge is offline.- Every run pays for the profile in tokens. A filled-in profile is a few hundred; the limits keep thelargest possible one to about 16,000 characters.- The Mac and Windows apps do not edit it yet.diff --git a/docs/guide/features/scheduling.md b/docs/guide/features/scheduling.mdindex 36e23dd..93fe9f1 100644--- a/docs/guide/features/scheduling.md+++ b/docs/guide/features/scheduling.md@@ -41,16 +41,17 @@ runs never fill up the History tab.The editor shows the next three runs before you save, and for an instruction how many agent runs aweek the schedule adds up to — each one spends tokens.-The daemon keeps the schedule, in `~/.browsentic/schedules.json`, so one list covers every browser+The Bridge keeps the schedule, in `~/.browsentic/schedules.json`, so one list covers every browserpaired with it. `browsentic tasks` lists the tasks from a terminal, and pauses, resumes or deletes one.### What has to be running-A run needs the browser open and the daemon up. The daemon starts itself when the browser needs it:-`browsentic setup` registers a small helper that Chrome, Edge, Brave and Firefox can launch, and+A run needs the browser open and Browsentic Bridge up. The Bridge starts itself when the browser+needs it: `browsentic setup`, or installing the app, registers a small helper that Chrome, Edge,+Brave and Firefox can launch, whether the extension came from a store or a folder, and`browsentic status` says which browsers have it.-After `browsentic stop` the browser leaves the daemon down until `browsentic start`, or an MCP+After `browsentic stop` the browser leaves the Bridge down until `browsentic start`, or an MCPclient, brings it back.A run that falls due while the browser is closed or the computer is asleep is **missed**. By defaultdiff --git a/docs/guide/features/site-maps.md b/docs/guide/features/site-maps.mdindex 75099f1..8645eee 100644--- a/docs/guide/features/site-maps.md+++ b/docs/guide/features/site-maps.md@@ -58,7 +58,7 @@ The crawl is **read-only and locked to one host**. It cannot click, fill or submthe site; and it is pinned to the tab it started in, so switching tabs stops it rather thanfollowing you. Off-host, every read is blocked until it navigates back.-Limits are enforced by the daemon, and [config](../configuration.md) can narrow them but never widen+Limits are enforced by the Bridge, and [config](../configuration.md) can narrow them but never widenthem:| Setting | Default | Ceiling |diff --git a/docs/guide/features/skills.md b/docs/guide/features/skills.mdindex 42eb286..5637ef6 100644--- a/docs/guide/features/skills.md+++ b/docs/guide/features/skills.md@@ -100,12 +100,12 @@ The `/` picker also lists the skills the active agent CLI keeps for itself:| Qwen Code | `~/.qwen/skills/`, `~/.agents/skills/` || OpenCode | `~/.config/opencode/skills/` (and `skill/`), `~/.opencode/skills/`, `~/.agents/skills/`, `~/.claude/skills/` |-Picking one attaches it to that message: the daemon reads the file at spawn time and+Picking one attaches it to that message: the Bridge reads the file at spawn time andappends it to the system prompt, clearly marked, with a note that browser tools are all the runhas.These never go through routing — they ride alongside whatever base skill was picked. Only the-skill's **title crosses to the extension**; the panel holds an opaque id, and the daemon refuses+skill's **title crosses to the extension**; the panel holds an opaque id, and the Bridge refusesany id it did not mint itself, so the file's path and content stay on your machine's daemon side.Files past 48 KB are left out of the picker. Switching agents swaps the list.diff --git a/docs/guide/install.md b/docs/guide/install.mdindex c7ee705..09a1357 100644--- a/docs/guide/install.md+++ b/docs/guide/install.md@@ -1,36 +1,59 @@# Install-Browsentic is two halves: a browser extension with a side panel, and the local daemon it talks to.-One command installs both. Then [pair them](pair.md) and open the panel.+Browsentic is your browser's superpower: a side panel that drives your real, logged-in browser with+the AI agent you already use. It is free and open source, with no API key, no account and no cloud+service of its own.-There is no account, no API key and no cloud service. Browsentic drives your real browser using the-AI agent you already run locally.+**Browsentic is two pieces plus the AI you already use.**++1. **The extension**, in your browser: from the Chrome Web Store, or the signed add-on for Firefox.+2. **Browsentic Bridge**, on your computer: the Mac app, the Windows app, or+ `npx browsentic@latest setup`. It runs your agent and keeps everything local.+3. **An agent CLI you're signed in to**: Claude Code, Codex, or another supported one. You probably+ have one already.++Install 1 and 2 in either order, then pair them once with a code.----## Prerequisites+## What you need| | Requirement | Check || --- | --- | --- |-| **Node** | 20 or newer | `node --version` |-| **Browser** | Chrome or another Chromium browser (Edge, Brave, Arc), or Firefox 140 or newer | — |-| **System** | macOS or Linux; Windows 10 or 11 is [experimental](limits.md#windows-is-experimental). macOS and Windows also have an app ([macOS](mac-app.md), [Windows](windows-app.md)) that brings its own Node | — |+| **Browser** | Chrome, Edge, Brave, Arc, Vivaldi, Opera or another Chromium browser, or Firefox 140 or newer | — |+| **System** | macOS, Windows 10 or 11 ([experimental](limits.md#windows-is-experimental)), or Linux | — |+| **Node** | 20 or newer, only for `npx`: the [Mac app](mac-app.md) and the [Windows app](windows-app.md) bring their own | `node --version` || **Agent** | One of [Claude Code](https://claude.com/claude-code), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google/docs/cli/install), [Mistral Vibe](https://github.com/mistralai/mistral-vibe) (beta), [Grok Build](https://docs.x.ai/build/overview) (beta), [Cursor CLI](https://cursor.com/docs/cli/overview) (beta), [Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/) (beta) or [OpenCode](https://opencode.ai/docs/cli/) (beta) on your `PATH`, logged in | `claude --version`, `codex --version`, `agy --version`, `vibe --version`, `grok --version`, `cursor-agent --version`, `qwen --version`, `opencode --version` |Two things worth knowing before you start:-- **The side panel runs on the agent CLI.** It is what the daemon spawns to reason about an+- **The side panel runs on the agent CLI.** It is what Browsentic Bridge starts to reason about aninstruction, so it is the one thing to have ready before your first run. See[Choosing an agent](agents.md). The only setup that needs no CLI is driving the browser solely- from an [MCP client](mcp-clients.md), which is optional and spawns nothing.+ from an [MCP client](mcp-clients.md), which is optional and starts nothing.- **Only one of them is needed.** Browsentic checks every one and tells you in the popup which areinstalled. Switching is a click.----## Install+## 1. Add the extension++| Browser | Get it from | What to press |+| --- | --- | --- |+| Chrome, Brave, Arc, Vivaldi | [Chrome Web Store](https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp) | **Add to Chrome** (in Brave, **Add to Brave**) |+| Edge | [Chrome Web Store](https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp) | **Allow extensions from other stores** in the bar at the top, then **Add to Chrome**. The Edge Add-ons listing is in review. |+| Opera | [Chrome Web Store](https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp) | Opera first offers its **Install Chrome Extensions** helper: add it, then **Add to Opera** |+| Firefox 140 or newer | [The signed add-on](https://browsentic.com/download/firefox) | Accept both prompts: one lets github.com install software, one adds Browsentic. See [Firefox](#firefox) |+| Ungoogled Chromium, a profile that blocks stores, an unreleased build | A folder on your computer | See [Load unpacked](#load-unpacked-advanced) |++Pin Browsentic to the toolbar from the puzzle-piece menu, so the popup is one click away.++You don't have to find the page yourself: the apps and `setup` open the right one in the browser you+pick.++## 2. Install Browsentic Bridge-On macOS there is an [app](mac-app.md) that does all of this from a window, Node included:+On macOS, the [app](mac-app.md) does it from a window, Node included:```shcurl -fsSL https://browsentic.com/install.sh | sh@@ -42,27 +65,36 @@ On Windows there is [one too](windows-app.md). In PowerShell:irm https://browsentic.com/install.ps1 | iex```-Everywhere else, and on either if you would rather not have the app:+Everywhere else, and on either if you would rather not have an app:```sh-npx browsentic setup+npx browsentic@latest setup```-That installs the extension to `~/browsentic/extension/chrome-mv3`, starts the daemon, and prints a-pairing code. The npm package carries the extension build, so nothing is compiled and nothing is-downloaded beyond the one package.+On a terminal, `setup` starts the Bridge, checks your agent, and asks which browser should get the+extension:-Two steps are left. Both happen inside the browser, so only you can do them.+```+ Browsentic 0.8.0 — your browser's superpower++ ✓ Browsentic Bridge running on 127.0.0.1:8765 (pid 4242)+ ✓ Wake-up Chrome, Edge, Firefox can start the Bridge when it is down+ ✓ Agent Claude Code · also ready: Codex-**1. Load the extension.** Open `chrome://extensions`, turn on **Developer mode** (top right),-press **Load unpacked**, and choose the folder the command printed. On macOS you can press ⇧⌘G in-the folder picker and paste the path; on Linux, Ctrl+L. On Windows the folder is-`%USERPROFILE%\browsentic\extension\chrome-mv3`. Using Firefox instead? Skip to [Firefox](#firefox).+ Which browser should get the extension?-Pin Browsentic to the toolbar so the popup is one click away.+ 1 Chrome Chrome Web Store+ 2 Edge Chrome Web Store+ 3 Firefox signed add-on+ 4 Another browser: load it unpacked++ › 1+```-**2. Paste the pairing code** into the popup and press Connect. It is single use and lives for ten-minutes. `browsentic pair` issues another.+It opens that browser's store page in that browser, prints a pairing code, and waits for the+browser to connect. `--browser chrome` (or `edge`, `brave`, `arc`, `vivaldi`, `opera`, `chromium`,+`firefox`) skips the question. With no terminal to ask on, `setup` prints the store links and a code+instead. The [CLI reference](../reference/cli.md) has every flag.To install the command permanently rather than through `npx`:@@ -70,51 +102,66 @@ To install the command permanently rather than through `npx`:npm i -g browsentic```-### Updating+## 3. Pair them, once-```sh-npx browsentic update-```+Click Browsentic in the toolbar, enter the code the app or `setup` shows, and press **Connect**. The+code works once and lives for ten minutes; `browsentic pair`, or **Get a pairing code** in the app,+issues another. The browser keeps the pairing from then on, so this is the only time you do it.+[Pairing](pair.md) has the detail.++---++## Updating-That replaces the command itself if the registry has something newer, refreshes the installed-extension in place, and restarts the daemon. The install path never changes, so your browser stays-paired. Press ↻ on the Browsentic card at `chrome://extensions` to pick up the new build. Firefox-takes its add-on from the release page instead and updates it on its own — see [Firefox](#firefox).+| What | How it updates |+| --- | --- |+| The extension from the Chrome Web Store | On its own, when the browser checks (every few hours). **Update** at `chrome://extensions`, with Developer mode on, checks now |+| The Firefox add-on | On its own, about once a day. `about:addons` → the gear → **Check for Updates** checks now |+| Browsentic Bridge, from an app | The app offers each release on its Overview tab; one press updates the app and the Bridge |+| Browsentic Bridge, from `npx` | `npx browsentic@latest update` |+| An unpacked copy | `browsentic update` rewrites the folder in place; press ↻ on its card |-### Uninstalling+The extension and the Bridge don't have to be the same version. A store copy can update before or+after the Bridge does, and they go on working: Browsentic Bridge 0.8 works with the extension from+0.7.14 on. `browsentic update` replaces the command if the registry has something newer and+restarts the Bridge on it; your browser stays paired.++## Uninstalling```shnpx browsentic uninstall```-One command for the daemon, both directories and the `npx` cache. It prints the plan and asks first.-Remove the card at `chrome://extensions` yourself, ideally before running it. See+One command for the Bridge, its directories and the `npx` cache. It prints the plan and asks first.+Remove the extension from each browser yourself (right-click its toolbar icon → **Remove**). See[Maintenance](maintenance.md).-### Firefox+----Release Firefox installs only add-ons that addons.mozilla.org has signed, so the Firefox build is-not loaded from a folder — it is a signed `.xpi` on every-[GitHub release](https://github.com/imshaikot/browsentic/releases/latest).+## Firefox++Release Firefox installs only add-ons that addons.mozilla.org has signed, so the Firefox build is a+signed `.xpi` on every [GitHub release](https://github.com/imshaikot/browsentic/releases/latest),+and [browsentic.com/download/firefox](https://browsentic.com/download/firefox) always points at the+newest one.```sh-npx browsentic setup --browser firefox+npx browsentic@latest setup --browser firefox```-That starts the daemon and prints two things: the link to the signed add-on for that same version,-and a pairing code. (The Mac app starts the same daemon; take the add-on from the release page.)+That starts the Bridge, opens the add-on for that same version in Firefox, and prints a pairing+code. The apps' **Get the Firefox add-on** button does the same.-**1. Install the add-on.** Open the link in Firefox and accept both prompts — one to let github.com-install software, one to add Browsentic. Or download `browsentic-<version>-firefox.xpi`, open-`about:addons`, press the gear, choose **Install Add-on From File…** and pick it. Either way-Firefox shows what the add-on asks for and installs it for good — it survives restarts, unlike-anything loaded through `about:debugging`. If the command says the file is not attached yet,-Mozilla is still signing that version; it appears within minutes, occasionally longer.+**1. Install the add-on.** Accept both prompts: one lets github.com install software, one adds+Browsentic. Or download `browsentic-<version>-firefox.xpi`, open `about:addons`, press the gear,+choose **Install Add-on From File…** and pick it. Either way it is installed for good: it survives+restarts, unlike anything loaded through `about:debugging`. If `setup` says the file is not attached+yet, Mozilla is still signing that version; it appears within minutes, occasionally longer.-**2. Paste the pairing code** into the popup and press Connect.+**2. Enter the pairing code** in the popup and press **Connect**.-Firefox checks the release page for a newer signed build about once a day and updates itself;-**Check for Updates** under the same gear does it now. There is no `↻` step and nothing to reload.+Firefox checks for a newer signed build about once a day and updates itself; there is no ↻ step and+nothing to reload.Nine tools that need Chrome's debugger — the trusted click, the captcha, diagnostics and page-codetools — do not exist on Firefox, and the agent there is not offered them. [Limits](limits.md) has@@ -124,6 +171,31 @@ Developer Edition and Nightly can still load `dist/firefox-mv2` from a source ch`xpinstall.signatures.required` set to `false`; that is the loop for working on the Firefox build,not for using it.+## Load unpacked (advanced)++For a browser that cannot reach a store (ungoogled Chromium, a managed profile that blocks it), or to+try a build the stores do not have yet. The npm package carries the extension build, so nothing is+compiled.++```sh+npx browsentic@latest setup --unpacked+```++That writes the extension to `~/browsentic/extension/chrome-mv3` and prints a pairing code. In the+apps, it is **Load it unpacked instead** under the extension rows.++1. Open your browser's extensions page (`chrome://extensions`, `brave://extensions`…) and turn on+ **Developer mode** (top right).+2. Press **Load unpacked** and choose that folder. On macOS, press ⇧⌘G in the folder picker and paste+ the path; on Linux, Ctrl+L. On Windows it is `%USERPROFILE%\browsentic\extension\chrome-mv3`.+3. Click Browsentic in the toolbar, enter the code and press **Connect**.++Keep the folder where it is: the browser names an unpacked extension after its path, and the pairing+belongs to that name. An update rewrites it in place, so press ↻ on its card afterwards.++**Switching to the store copy.** Remove the unpacked card first, then add Browsentic from the store+and pair it once. Two copies in one browser both answer, and `browsentic status` flags it.+---## From source@@ -136,7 +208,7 @@ cd browsenticnode scripts/setup.mjs```-That runs four steps: extension dependencies, extension build, daemon dependencies, daemon build.+That runs four steps: extension dependencies, extension build, Bridge dependencies, Bridge build.`src/daemon/` is a separate Yarn project with its own lockfile, which is why the root install does notcover it. Yarn itself is not a prerequisite: the pinned Yarn 4 release ships inside the repositoryand the setup script invokes it through Node.@@ -145,15 +217,15 @@ When it finishes you have:```dist/chrome-mv3 the unpacked extension-src/daemon/dist the daemon and MCP server+src/daemon/dist Browsentic Bridge: the Bridge, the CLI and the MCP server```Load `dist/chrome-mv3` directly through **Load unpacked**, or put the CLI on your `PATH` with-`yarn daemon:link` and let `browsentic setup` install from the checkout. Either way Chrome will not-auto-reload the extension after a rebuild, so press ↻ on its card yourself.+`yarn daemon:link` and run `browsentic setup --unpacked` from the checkout. Either way the browser will+not reload the extension after a rebuild, so press ↻ on its card yourself.---## Next-**[Pair your browser →](pair.md)** — the extension connects to nothing until you do.+**[Your first run →](first-run.md)** — open the side panel and give it something to do.diff --git a/docs/guide/limits.md b/docs/guide/limits.mdindex 2ebc52b..868430f 100644--- a/docs/guide/limits.md+++ b/docs/guide/limits.md@@ -97,7 +97,7 @@ yet, so the popup, the docs and the release notes say *beta*. What that means in## Windows is experimental-The daemon runs on Windows and its tests run there on every change. On a Windows 11 desktop it has+The Bridge runs on Windows and its tests run there on every change. On a Windows 11 desktop it hasbeen set up, paired and driven from the side panel by Claude Code; a cancelled run, the other agentsand the [Windows app](windows-app.md) have not been taken through one yet. Until they have:@@ -153,7 +153,7 @@ a partial image.`page_trustedClick`, the two captcha tools, the four [diagnostics](features/diagnostics.md) toolsand the two [page-code](features/page-actions.md) tools are built on the Chrome DevTools Protocol,which Firefox does not expose. A Firefox build leaves them off the list it offers, so an agent-running there never sees them and the daemon reports the shorter list as in sync. A stale skill or+running there never sees them and the Bridge reports the shorter list as in sync. A stale skill orrecording that still names one gets `UNSUPPORTED`, with a hint. There is no fallback for thediagnostics ones — a page's console and network activity are not reachable any other way.@@ -175,13 +175,23 @@ was. See [Theming](features/theming.md).## Loopback ports-The daemon binds the first free port of 8765, 8766, 8767. If all three are taken it will not start.+Browsentic Bridge binds the first free port of 8765, 8766, 8767. If all three are taken it will not+start.++## The Bridge's wake-up helper++So a browser can start Browsentic Bridge when it is down, setup registers a native messaging host+with each browser it finds. Only Browsentic's own extensions may launch it — the Chrome Web Store and+Edge Add-ons copies by their IDs, the unpacked folder, and the signed Firefox add-on — and it does+nothing but start the Bridge. The trust boundary is unchanged: your user account. Opera, and Vivaldi+and Arc on Windows, are not registered yet, so there the Bridge starts with the app, a command or an+MCP client instead.## Unpacked extension-Installing from source means Chrome will not auto-update it, and will not auto-reload it after a-rebuild — press ↻ at `chrome://extensions`. Chrome may also prompt about developer-mode extensions-on each launch.+An unpacked copy — `setup --unpacked`, or a source build — is not updated by any store, and the+browser will not reload it after a rebuild or an update: press ↻ at `chrome://extensions`. Chrome may+also prompt about developer-mode extensions on each launch. The store copies have neither problem.---diff --git a/docs/guide/mac-app.md b/docs/guide/mac-app.mdindex 3a3a874..f7eb36e 100644--- a/docs/guide/mac-app.md+++ b/docs/guide/mac-app.md@@ -1,8 +1,9 @@# Browsentic for macOS-A native app that installs Browsentic and runs it from a window. It is the same command and the-same daemon as [`npx browsentic setup`](install.md) — the app carries them inside itself, lays them-down in `~/.browsentic`, and then drives them, so nothing here needs a terminal.+Browsentic Bridge, the half of Browsentic that runs on your computer, as a native app. It is the same+command and the same background process as [`npx browsentic@latest setup`](install.md) — the app+carries them inside itself, lays them down in `~/.browsentic`, and then drives them, so nothing here+needs a terminal. It also adds the other half, the extension, to your browsers from their stores.Requires macOS 14 or newer, on Apple silicon or Intel. On Windows, the [Windows app](windows-app.md) is the same thing.@@ -37,51 +38,64 @@ Right-click ▸ Open no longer gets past this on macOS 15 and newer. The one-lin## The first screen: what your Mac already has-The app opens on six checks and runs them on its own:+The app opens on five checks and runs them on its own:| Check | Passes when | If it does not || --- | --- | --- || **This Mac** | always | — || **Node.js runtime** | `node` 20 or newer is on your `PATH` | **Install** downloads the current LTS from nodejs.org into `~/.browsentic/runtime/node`, verified against its published SHA-256. No Homebrew, no password |-| **Browsentic command** | `~/.browsentic/cli` holds the version this app carries | **Install** copies it there and writes the `browsentic` launcher to `~/.browsentic/bin` |-| **Browser extension** | the same version is unpacked at `~/browsentic/extension/chrome-mv3` | **Install** unpacks it |-| **A Chromium browser** | Chrome, Brave, Edge, Arc, Vivaldi, Opera or Chromium is installed | **Get Chrome** opens the download page. Advisory — it does not block you |+| **Browsentic Bridge** | `~/.browsentic/cli` holds the version this app carries | **Install** copies it there, writes the `browsentic` launcher to `~/.browsentic/bin`, and registers it with your browsers so they can start it |+| **A browser** | Chrome, Brave, Edge, Arc, Vivaldi, Opera, Chromium or Firefox is installed | **Get Chrome** opens the download page. Advisory — it does not block you || **An AI agent** | One of `claude`, `codex`, `agy`, `vibe`, `grok`, `cursor-agent`, `qwen` or `opencode` is on your `PATH` | **Install Claude Code** runs `npm i -g @anthropic-ai/claude-code`. Advisory |-**Set up everything** installs the first three in one click. A browser and an agent are yours to-choose, so each has a button of its own. When everything required is in place the app moves on by-itself; on later launches that takes about two seconds.+**Set up everything** installs Node and the Bridge in one click. A browser, the extension and an+agent are yours to choose, so each has a button of its own. When everything required is in place+the app moves on by itself; on later launches that takes about two seconds.-> **Why the extension is not in `~/.browsentic`.** Chrome’s **Load unpacked** dialog is the-> system folder picker, which hides dotfolders, and a browser’s pairing is tied to the extension’s-> absolute path. So the extension lives in `~/browsentic/extension/chrome-mv3`, exactly where the-> command puts it, and everything else goes in `~/.browsentic`.+## Adding the extension++**Overview** lists the browsers on your Mac, one row each, with where the extension comes from and+whether it is connected. A browser without it has a button — **Add to Chrome**, **Add to Edge**,+**Get the Firefox add-on** — that opens its store page in that browser and shows a pairing code.+Press the store's button, click Browsentic in the toolbar, enter the code, and the row turns+**Connected**. Edge installs from the Chrome Web Store until its own listing is published; the app+tells you to press **Allow extensions from other stores** first.++**Load it unpacked instead**, under the rows, is for a browser that cannot reach a store or for an+unreleased build. It writes the extension to `~/browsentic/extension/chrome-mv3`, opens+`chrome://extensions` with that path on the clipboard, and shows **Reload needed** on that row when+the folder holds a newer build than the browser has loaded.++> **Why an unpacked extension is not in `~/.browsentic`.** Chrome’s **Load unpacked** dialog is the+> system folder picker, which hides dotfolders, and the browser names an unpacked extension after+> its absolute path. So it lives in `~/browsentic/extension/chrome-mv3`, exactly where the command+> puts it, and everything else goes in `~/.browsentic`.## The windowThe tabs float at the top; ⌘1–⌘8 switch between them.--++-+| Tab | What you do there || --- | --- |-| **Overview** | Turn the daemon on and off with the power button, restart it, see its address, version and whether the extension is connected and in sync. Copy the extension’s path, or open `chrome://extensions` in your browser with the path already on the clipboard |-| **Browsers** | Get a [pairing code](pair.md) with a live countdown, see every paired browser, unpair one or all |+| **Overview** | Turn Browsentic Bridge on and off with the power button, restart it, see its address and version. One row per browser: where its extension comes from, whether it is connected, and a button that adds it from the store. The unpacked folder sits behind **Load it unpacked instead** |+| **Browsers** | Get a [pairing code](pair.md) with a live countdown, see every paired browser and the store its extension came from, unpair one or all || **Agents** | See which of the seven agent CLIs are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs || **Skills** | Every [skill](features/skills.md) the router can see and which folder it came from || **Activity** | Your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured || **Logs** | `~/.browsentic/daemon.log`, followed live |-| **Settings** | Light, dark or system appearance for this window; whether the daemon starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall |+| **Settings** | Light, dark or system appearance for this window; whether the Bridge starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall || **About** | Who makes Browsentic, a GitHub star, every version on this computer with a copy button, **Report a bug** (GitHub's issue form with those versions filled in — nothing is sent until you submit it), and links to the guide, this page, [troubleshooting](troubleshooting.md) and the release notes. **Run the checks again** reruns the first-run checks |-There is also a menu bar item with the daemon’s state and the same on, off and restart.+There is also a menu bar item with the Bridge’s state and the same on, off and restart.-**Closing the window does not stop anything.** The daemon is a background process of its own, so+**Closing the window does not stop anything.** The Bridge is a background process of its own, sothe side panel and any MCP client keep working with the app closed or quit.## `browsentic` in your terminal@@ -99,9 +113,10 @@ not two that can drift apart.The app asks GitHub and npm for a newer release when it opens and every few hours after. When oneis out, a card appears at the top of **Overview** (and in Settings) with **Update now**: it downloadsthe release, checks its signature and that it is the version it claims to be, replaces the app and-reopens it, and the new app replaces the command and the extension and restarts the daemon. Then-press ↻ on the Browsentic card at `chrome://extensions`, which is the one step no installer can do-for you. **Check for updates** on the same card asks again on the spot.+reopens it, and the new app replaces the Bridge and restarts it. The extension updates itself from+its store; only an unpacked copy needs ↻ on its card at `chrome://extensions`, and the app says so.+The two don't have to be the same version. **Check for updates** on the same card asks again on the+spot.A release reaches npm a few minutes before its Mac build is attached; until then the card says soand offers **Check again** instead. If an update fails nothing is changed, and the card hands you@@ -112,9 +127,9 @@ the install line, which installs the same release from a terminal.## Uninstall**Settings → Uninstall…** runs [`browsentic uninstall`](../reference/cli.md#uninstall): it unpairs-every browser, stops the daemon and removes `~/.browsentic` and `~/browsentic`, optionally keeping-your skills. Remove the Browsentic card at `chrome://extensions` first, and drag the app to the-Trash afterwards.+every browser, stops the Bridge and removes `~/.browsentic` and `~/browsentic`, optionally keeping+your skills. Remove Browsentic from each browser first (right-click its toolbar icon → **Remove**),+and drag the app to the Trash afterwards.## Building it yourselfdiff --git a/docs/guide/maintenance.md b/docs/guide/maintenance.mdindex 2a813b4..cb8e57e 100644--- a/docs/guide/maintenance.md+++ b/docs/guide/maintenance.md@@ -4,15 +4,25 @@## Updating+Each half updates on its own, and they don't have to be the same version. Browsentic Bridge 0.8+works with the extension from 0.7.14 on, older or newer than itself, so a store copy that updates+first, or last, keeps working.++| What | How |+| --- | --- |+| The extension from the Chrome Web Store | Updates itself when the browser checks, every few hours. **Update** at `chrome://extensions`, with Developer mode on, checks now |+| The Firefox add-on | Updates itself: every release publishes a signed `.xpi` and an `updates.json` beside it, Firefox polls that file about once a day, and **Check for Updates** in `about:addons` polls it now |+| Browsentic Bridge, from the Mac or Windows app | The app's **Update now** card ([macOS](mac-app.md#updating), [Windows](windows-app.md#updating)) |+| Browsentic Bridge, from `npx` or `npm` | `browsentic update`, below |+| An unpacked copy | `browsentic update` rewrites the folder, then press ↻ on its card |+```shbrowsentic update```-That refreshes two things, in order: **the command itself**, then the extension it carries.--The Firefox add-on is not carried by the package. It updates itself: every release publishes a-signed `.xpi` and an `updates.json` beside it, Firefox polls that file about once a day, and-**Check for Updates** in `about:addons` polls it now. `browsentic update` still refreshes the daemon.+That refreshes, in order: **the command itself**, restarting the Bridge on it, then the unpacked+extension folder if you load one. A store copy is not in the package; `update` says it updates+itself.The first half matters more than it sounds. `npx browsentic setup` does not put anything on your`PATH` — it runs the package out of npm's own throwaway cache, and npm names that directory after@@ -20,7 +30,7 @@ the spec it was asked for, records the version it resolved *the first time*, andwithout asking the registry again. So a machine set up with `npx` keeps running whatever version itfirst saw, and since the extension ships inside the package, `update` had nothing newer to installand reported "already current" every time. It now checks the registry, replaces the stale cache, and-re-runs itself under the new version.+re-runs itself under the new version. `npx browsentic@latest` asks the registry every time.`--no-self-update` skips the check, and a pinned `npx browsentic@<version>` is never upgraded past —a pin is a decision, not a stale cache.@@ -32,17 +42,17 @@ git pullyarn setup```-Either way the last step is yours: **nothing reloads itself.** Chrome does not auto-reload an-unpacked extension, so press ↻ on the Browsentic card at `chrome://extensions`. `browsentic update`-has already replaced the daemon; from a clone, `browsentic restart` is that half, because a running-daemon keeps the old build in memory until it is swapped out.--`browsentic status` names both versions when they disagree, and says which one to reload.+An unpacked copy is the one thing that never reloads itself: press ↻ on its card at+`chrome://extensions`. `browsentic update` has already replaced the Bridge; from a clone,+`browsentic restart` is that half, because a running Bridge keeps the old build in memory until it+is swapped out. `browsentic status` names each browser's version, and says which unpacked copy to+reload.-**Rebuild both halves together.** If only one side is rebuilt, `browsentic status` reports-`manifest: DRIFTED`. The daemon then falls back to the tools the browser actually has and tells-your MCP clients the list changed — it degrades loudly rather than into tool calls that fail at the-far end — but you should fix the drift rather than run on it.+**When the two halves list different tools.** A store copy a version ahead of the Bridge, or behind+it, can carry a different set of tools. The Bridge then serves the tools the browser actually has+and tells your MCP clients the list changed, and `browsentic status` reports `tools: the+extension's own list`. That is normal while one side waits on its update. From a clone, rebuild both+halves together.Your pairing survives updates. `yarn daemon:link` only needs re-running if the link is broken.@@ -58,7 +68,7 @@ Nothing is lost by it — accepting reconnects the pairing you already had.### Why `yarn daemon:build` alone changes nothing-The daemon has no start command: the first CLI or MCP client that needs it spawns it, and it lives+The Bridge has no start command: the first CLI or MCP client that needs it spawns it, and it livesuntil `browsentic stop` or 30 idle minutes with nothing attached. A rebuild does not touch theprocess already running.@@ -73,16 +83,16 @@ the fresh build.browsentic uninstall```-On Firefox, remove the add-on from `about:addons` as well — it was installed from a file, not from-the directory this command removes.+Remove the extension from each browser as well (right-click its toolbar icon → **Remove**, or+`about:addons` in Firefox): a store copy was never in the directories this command removes.It prints exactly what it is about to remove and asks before removing any of it:| | || --- | --- |-| daemon | Whatever is *answering* on 8765–8767, not what the lockfile claims. Sessions are revoked through it first, so a connected browser is told it is unpaired rather than left to discover it |+| Bridge | Whatever is *answering* on 8765–8767, not what the lockfile claims. Sessions are revoked through it first, so a connected browser is told it is unpaired rather than left to discover it || state | `~/.browsentic` — pairing keys, config, approvals, logs |-| files | `~/browsentic` — the unpacked extension, skills, site maps, screenshots, captured downloads |+| files | `~/browsentic` — the unpacked extension if you used one, skills, site maps, screenshots, captured downloads || npx cache | Every `~/.npm/_npx/*` directory holding a copy of the package || Flag | Does |@@ -91,9 +101,10 @@ It prints exactly what it is about to remove and asks before removing any of it:| `--yes` / `-y` | Skip the confirmation. Required when stdin is not a terminal, since there is nobody to ask || `--keep-skills` | Leave `skills/` behind. Nothing else has a copy of your site maps |-**Remove the card at `chrome://extensions` first.** That is the one step no command can do for you,-and doing it afterwards leaves the browser holding a folder that is no longer there. It is also what-clears recordings and held secrets, which live in extension storage rather than on disk.+**Remove the extension from your browsers first.** That is the one step no command can do for you.+It is also what clears recordings and held secrets, which live in extension storage rather than on+disk, and for an unpacked copy, doing it afterwards leaves the browser holding a folder that is no+longer there.Two things it names but will not touch: the command itself (`npm rm -g browsentic`, or`yarn daemon:unlink` from a clone) and the entry in your MCP client@@ -114,8 +125,8 @@ never notices — it holds its port for as long as the machine is up, and nothinlockfile, so it finds that one too.If you would rather do it by hand, the order is: `browsentic revoke`, `browsentic stop`, remove the-card at `chrome://extensions`, `rm -rf ~/.browsentic ~/browsentic`, then delete every-`~/.npm/_npx/*` directory containing `node_modules/browsentic`. `revoke` needs the daemon, so it+extension from each browser, `rm -rf ~/.browsentic ~/browsentic`, then delete every+`~/.npm/_npx/*` directory containing `node_modules/browsentic`. `revoke` needs the Bridge, so itcomes before `stop`; the cache is the step people miss.What those directories held is listed in [internals/state.md](../internals/state.md) — worth a look@@ -131,7 +142,7 @@ yarn dev # build, launch a throwaway Chrome profile, hot reloadyarn dev:firefoxyarn build # production buildyarn zip # store-ready archive-yarn daemon:dev # rebuild the daemon on change+yarn daemon:dev # rebuild the Bridge on changeyarn daemon:restart # rebuild, then swap the running daemon for the fresh buildyarn daemon:manifest # print the tool manifest, no browser neededyarn check # both type checks plus both fixture suitesdiff --git a/docs/guide/mcp-clients.md b/docs/guide/mcp-clients.mdindex 20ee1dc..4853918 100644--- a/docs/guide/mcp-clients.md+++ b/docs/guide/mcp-clients.md@@ -1,7 +1,7 @@# Driving Browsentic from an MCP client**Optional.** The side panel is the product and needs none of this. But pairing connects your-*browser* to the daemon, and registering an MCP client lets **that client** drive the same browser+*browser* to the Bridge, and registering an MCP client lets **that client** drive the same browsertoo — Claude Code, Codex, Cursor, Zed, Gemini CLI, Claude Desktop, anything that speaks MCP.This direction is fully agent-agnostic. Nothing here depends on which CLI you picked in@@ -58,7 +58,7 @@ Tools missing from a session you registered mid-flight is the single most common| `browsentic://page/text` | You only need the rendered prose |The tool list is generated from the same registry the extension ships, so it cannot describe-something the browser cannot do. If the two halves *are* built from different registries, the daemon+something the browser cannot do. If the two halves *are* built from different registries, the Bridgeadopts the browser's list and tells your client the tools changed.---@@ -70,7 +70,7 @@ changes is everything around the tool call.| | Side panel | MCP client || --- | --- | --- |-| Agent | The CLI you picked, spawned by the daemon | Whatever you registered |+| Agent | The CLI you picked, spawned by the Bridge | Whatever you registered || Consequential actions | Prompt you in the panel | **Refused** — see below || Host confinement | Scoped to the sites the run is about | Unconfined || Timeline | Every action, live | Actions appear tagged `external` |diff --git a/docs/guide/pair.md b/docs/guide/pair.mdindex 77bad3f..263b6ad 100644--- a/docs/guide/pair.md+++ b/docs/guide/pair.md@@ -1,13 +1,14 @@# Pair your browser-A fresh install connects to nothing. Pairing is what tells the daemon that this browser is yours.+A fresh install connects to nothing. Pairing is what tells Browsentic Bridge that this browser is+yours, and you do it once per browser.-Assumes you have [installed and loaded the extension](install.md).+Assumes you have [added the extension and installed the Bridge](install.md).----`browsentic setup` already printed a code and you may have used it. This page is what to do when-you need another one, or when you are pairing a second browser.+`browsentic setup` and the apps already showed a code, and you may have used it. This page is what+to do when you need another one, or when you are pairing a second browser.---@@ -23,7 +24,7 @@ Through `npx`, if you have not installed the command globally:npx browsentic pair```-This starts the daemon if it is not already running and prints a code:+This starts the Bridge if it is not already running and prints a code:```Pairing code: K7QM-3XPT@@ -32,10 +33,12 @@ This starts the daemon if it is not already running and prints a code:Expires in 10 minutes and works once.```-Open the Browsentic popup, paste the code, press **Connect**.+Click Browsentic in the toolbar, enter the code, press **Connect**. In the apps, **Get a pairing+code** on the Overview tab does the same. Up to three codes are live at once, so a code the app shows+keeps working while a terminal mints another.-The daemon issues a long-lived session key that survives browser and daemon restarts, and dies only-when you revoke it. You do not need to pair again after an update.+The Bridge issues a long-lived session key that survives browser and Bridge restarts, and dies only+when you revoke it. You do not need to pair again after an update, on either side.## 2. Verify@@ -44,22 +47,24 @@ browsentic status``````-daemon: running on 127.0.0.1:8765 (pid 41207, v0.3.1)-installed: v0.3.1 at /Users/you/browsentic/extension/chrome-mv3-extension: connected (v0.3.1)-manifest: in sync-paired: 1+bridge: running on 127.0.0.1:8765 (pid 41207, v0.8.0)+wake-up: Chrome, Brave can start the Bridge+agent: Claude Code — 2.1.0 (Claude Code)+browsers:+ ● Google Chrome v0.8.0 Chrome Web Store connected+ ○ Brave v0.8.0 unpacked not connected+tools: in sync```Every line matters:| Line | What it means || --- | --- |-| `daemon` | The local process is up, on one of ports 8765–8767 |-| `installed` | The extension build on disk. If it names a newer version than `extension`, the browser is still running the old one: press ↻ on its card |-| `extension` | Your browser is connected right now. `not connected` means the browser is closed or unpaired |-| `manifest` | `in sync` means both halves were built from the same action registry. `DRIFTED` means [rebuild both](maintenance.md) |-| `paired` | How many browsers hold a session key |+| `bridge` | The local process is up, on one of ports 8765–8767 |+| `wake-up` | Which browsers can start the Bridge when it is down |+| `agent` | The CLI the side panel runs on, and whether it is ready |+| `browsers` | One row per paired browser: its extension version, where the extension came from, and whether it is connected right now. An unpacked copy a build behind the folder on disk says to press ↻; a store copy updates itself. Two copies answering in one browser are flagged |+| `tools` | `in sync` means both halves were built from the same action registry. When the extension is a version ahead or behind, the tools come from the extension, which is fine |---@@ -67,12 +72,17 @@ Every line matters:Worth understanding, because it is easy to assume it does more than it does.-Any web page can open a WebSocket to loopback, so the daemon classifies every connection by its+Any web page can open a WebSocket to loopback, so the Bridge classifies every connection by itshandshake `Origin` — a value browsers set themselves and page JavaScript cannot forge. A web pageis refused outright. An extension origin must then prove it holds a pairing code or a session key,-and the daemon proves itself back, so another local process cannot squat the port and pose as your+and the Bridge proves itself back, so another local process cannot squat the port and pose as yourdaemon. Neither secret ever crosses the wire.+The browser can also start the Bridge when it is down, through a native messaging host that setup+registers with each browser. Only Browsentic's own extensions may launch it: the Chrome Web Store+and Edge Add-ons copies by their IDs, the unpacked folder, and the signed Firefox add-on. It starts+the Bridge and nothing more; it pairs nothing.+What pairing does **not** do is authenticate local programs. Anything running as your user can read`~/.browsentic/daemon.json` and drive an already-paired browser. Browsentic treats your user accountas the trust boundary. See [Limits](limits.md#pairing-controls-which-browser-not-which-process) and,@@ -90,8 +100,8 @@ browsentic revoke <id> # unpair one, by the id "sessions" printsSeveral browsers can be paired **and connected at once** — Chrome beside Brave, or two Chromeprofiles. Each pairs with its own code and keeps its own key, and the side panel in each runs on its-own. Every Chromium browser that loads the same folder presents the same extension origin, so a-browser is known by an install id it mints on first run, never by its origin.+own. Every browser that installs from the same store, or loads the same folder, presents the same+extension origin, so a browser is known by an install id it mints on first run, never by its origin.A newer connection supersedes an older one only when both come from the same browser profile.diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex c565a20..083c5cf 100644--- a/docs/guide/troubleshooting.md+++ b/docs/guide/troubleshooting.md@@ -7,12 +7,12 @@ Symptom, cause, fix. For what an error *code* means, see [reference/errors.md](.## Start here```sh-browsentic status # daemon, extension, manifest sync, pairings+browsentic status # the Bridge, each paired browser and its store, the agentbrowsentic agent # which agents are installed, which one runs the side panelbrowsentic logs # run starts, routed skills, every tool call and its outcome```-Those three answer most questions. The daemon log also lives at `~/.browsentic/daemon.log`.+Those three answer most questions. Browsentic Bridge's log also lives at `~/.browsentic/daemon.log`.---@@ -20,9 +20,15 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| Symptom | Cause | Fix || --- | --- | --- |+| The popup says `protocol version mismatch: daemon speaks v20` (any number below 22) | Browsentic Bridge is older than the extension: anything before 0.7.14 | Update the Bridge: **Update now** in the app, or `npx browsentic@latest update`. Then enter a new pairing code in the popup, because this version of the extension waits for one after a refusal |+| The popup says `protocol version mismatch: Browsentic Bridge speaks v22 and takes extensions from v22 on` | The extension is older than 0.7.14: an unpacked copy nobody updated | Remove it and add Browsentic from the store, or `browsentic update` and press ↻ on its card |+| The store copy is a version behind the Bridge | The browser has not checked for updates yet | Nothing breaks meanwhile: the two work across versions. **Update** at `chrome://extensions`, with Developer mode on, checks now |+| `browsentic status` says two copies of Browsentic answer in one browser | An unpacked copy and a store copy are both installed, and both inject into every page | Remove the unpacked card at the browser's extensions page |+| Edge will not install from the Chrome Web Store | Edge installs from other stores only once you allow it | Press **Allow extensions from other stores** in the bar at the top of the store page, confirm, then **Add to Chrome** |+| `browsentic setup` keeps waiting for the browser | The extension is in, but not paired yet | Click Browsentic in the toolbar and enter the code `setup` printed. Ctrl-C stops the wait without undoing anything || Popup shows `Expected {op:…}` | Stale service worker after a rebuild | `chrome://extensions` → ↻ reload Browsentic || "That pairing code is wrong or expired" | Codes are single-use and last 10 minutes | `browsentic pair` for a fresh one. A failed attempt does not burn the outstanding code |-| "No Browsentic daemon is running" | Nothing on 8765–8767 | `browsentic status`; check `browsentic logs` |+| "No Browsentic daemon is running" | Browsentic Bridge is not installed, or not running on 8765–8767 | Install it ([Install](install.md#2-install-browsentic-bridge)), or open the app, or `browsentic start`. Then `browsentic status`; check `browsentic logs` || `browsentic: command not found` | The global npm prefix is not on `PATH` | `npm prefix -g`, then add its `bin` directory || "Browsentic has not been given the microphone yet" | A browser cannot show its microphone prompt inside a side panel or a popup, so a fresh install has never been asked | Press **Allow microphone** and choose **Allow** in the tab that opens || "Microphone access is blocked" | The microphone was refused for the extension | Press **Allow microphone**, then click the icon at the left of that tab's address bar and set **Microphone** to **Allow** |@@ -33,12 +39,12 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| The hands-free mic turns amber and says another page took the microphone | Chrome runs one speech recognizer at a time, and another page or the panel started one | Press the mic to take it back || Holding Control does nothing | Hold to talk is off; the key went to a frame embedded in the page (some editors); another key or a click joined it; or the mic is muted | Turn **Hold to talk** on from the mic's menu, click the page outside the embedded editor, and hold left Control on its own || `EXTENSION_OFFLINE` | Browser closed, or not paired | Open the browser; `browsentic sessions` to check pairing |-| After a reboot the panel stays offline until you run a command | The browser has no helper registered to start the daemon | Run `browsentic setup` once. `browsentic status` then lists the browsers under `wake-up:` |+| After a reboot the panel stays offline until you run a command | The browser has no helper registered to start the Bridge, or one a Bridge before 0.8 registered, which lets in only the unpacked copy | Run `browsentic setup` once, or start Browsentic Bridge 0.8 once, which rewrites the registration. `browsentic status` then lists the browsers under `wake-up:` || The panel stays offline after `browsentic stop` | A stop holds the browser's wake-up, so the daemon stays down as asked | `browsentic start`. `browsentic status` says `held` while it lasts || A scheduled task shows **Missed** | The browser was closed, the computer asleep, or no daemon was running at that time | Nothing to fix — it runs once when things are back unless the task says **Skip it**. `browsentic status` shows whether the browser can start the daemon itself |-| "Load unpacked" cannot see `~/browsentic` | A Flatpak or Snap browser, sandboxed away from your home directory. Snap Chromium is the Ubuntu default | Grant it: `flatpak override --user --filesystem=~/browsentic com.google.Chrome`. Or install somewhere the sandbox can read: `browsentic setup --dir ~/snap/chromium/common/browsentic-extension` |+| "Load unpacked" cannot see `~/browsentic` | A Flatpak or Snap browser, sandboxed away from your home directory. Snap Chromium is the Ubuntu default | Add Browsentic from the Chrome Web Store instead, which needs no folder. Or grant it: `flatpak override --user --filesystem=~/browsentic com.google.Chrome`, or install somewhere the sandbox can read: `browsentic setup --unpacked --dir ~/snap/chromium/common/browsentic-extension` || The folder picker does not show `~/browsentic` | It is there; some pickers open elsewhere by default | macOS: press ⇧⌘G and paste the path. Linux: Ctrl+L. Windows: paste `%USERPROFILE%\browsentic\extension\chrome-mv3` into the picker's address bar |-| Updated with `npx`, but the browser still runs the old build | Chrome never auto-reloads an unpacked extension | `browsentic status` names both versions. Press ↻ on the Browsentic card |+| Updated, but an unpacked copy still runs the old build | A browser never reloads an unpacked extension by itself | `browsentic status` names both versions. Press ↻ on the Browsentic card. A store copy updates itself || `browsentic update` says "already current" forever, and reinstalling still lands on an old build | npm's `npx` cache serves the version it first resolved and never asks the registry again | `browsentic update` now replaces the cached command before installing. To clear it by hand, delete every `~/.npm/_npx/*` directory containing `node_modules/browsentic` || Deleted `~/.browsentic`, but a daemon is still holding port 8765 | The lockfile went with it; the process did not notice | `browsentic stop` probes the ports rather than the lockfile, so it finds that one. `browsentic uninstall` does it as part of the sweep |@@ -52,7 +58,7 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| `page_readNetwork` with `includeBodies` is denied | `network-body-read` is denied by default | Read status, timing and `includeHeaders` instead, or set `{"guardrails":{"rules":{"network-body-read":"allow"}}}` || `page_readConsole` comes back empty | Nothing was attached when the error happened | `page_startDiagnostics` **first**, then reproduce. `reload: true` catches load-time errors || `DEBUGGER_UNAVAILABLE` on `page_startDiagnostics` | DevTools is open on that tab — Chrome allows one debugger per tab | Close DevTools and retry |-| `manifest: DRIFTED` | Extension and CLI built from different registries | `yarn build && yarn daemon:restart`, then reload the extension |+| `tools: the extension's own list` | The extension and Browsentic Bridge are different versions, so their tool lists differ | Normal while one of them waits on an update; the tools come from the extension, which runs them. From a clone: `yarn build && yarn daemon:restart`, then reload the extension |## Agents@@ -99,7 +105,7 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| Symptom | Cause | Fix || --- | --- | --- |-| `TAB_UNREACHABLE` on a normal site | The extension needs reloading | ↻ at `chrome://extensions`; ordinary sites otherwise self-heal |+| `TAB_UNREACHABLE` on a normal site | The extension needs reloading | Turn Browsentic off and on at `chrome://extensions` (↻ on an unpacked copy); ordinary sites otherwise self-heal || `TAB_UNREACHABLE` on `chrome://`, the Web Store, the new-tab page | Those pages cannot host a content script | `page_navigate` to an http(s) page — it still works there || `TARGET_NOT_FOUND` for something clearly on screen | The page changed since the snapshot, or it is inside a captcha widget's shadow root | Re-snapshot with `page_getPageInfo`; for a captcha use [`page_solveCaptcha`](features/captcha.md) || A captcha keeps setting new image challenges | The vendor distrusts the browser, however well each round is answered — common with automated or headless browsers | Solve one round yourself in the page; a person's answer usually clears the distrust. See [Captchas](features/captcha.md#image-challenges) |diff --git a/docs/guide/windows-app.md b/docs/guide/windows-app.mdindex 59e4088..9c6b486 100644--- a/docs/guide/windows-app.md+++ b/docs/guide/windows-app.md@@ -1,9 +1,10 @@# Browsentic for Windows-An app that installs Browsentic and runs it from a window, the Windows counterpart of the-[macOS app](mac-app.md). It is the same command and the same daemon as-[`npx browsentic setup`](install.md): the app carries them inside itself, lays them down in-`%USERPROFILE%\.browsentic`, and then drives them, so nothing here needs a terminal.+Browsentic Bridge, the half of Browsentic that runs on your computer, as an app: the Windows+counterpart of the [macOS app](mac-app.md). It is the same command and the same background process+as [`npx browsentic@latest setup`](install.md): the app carries them inside itself, lays them down in+`%USERPROFILE%\.browsentic`, and then drives them, so nothing here needs a terminal. It also adds the+other half, the extension, to your browsers from their stores.Requires Windows 10 or 11, on x64 or ARM64. Windows is still [experimental](limits.md#windows-is-experimental).@@ -36,19 +37,18 @@ missing).## The first screen: what your computer already has-The app opens on six checks and runs them on its own:+The app opens on five checks and runs them on its own:| Check | Passes when | If it does not || --- | --- | --- || **This computer** | always | — || **Node.js runtime** | `node` 20 or newer is on your `PATH` | **Install** downloads the current LTS from nodejs.org into `%USERPROFILE%\.browsentic\runtime\node`, verified against its published SHA-256. No administrator |-| **Browsentic command** | `%USERPROFILE%\.browsentic\cli` holds the version this app carries | **Install** copies it there and writes the `browsentic.exe` launcher to `%USERPROFILE%\.browsentic\bin` |-| **Browser extension** | the same version is unpacked at `%USERPROFILE%\browsentic\extension\chrome-mv3` | **Install** unpacks it |-| **A Chromium browser** | Chrome, Edge, Brave, Vivaldi, Opera or Chromium is installed | **Get Chrome** opens the download page. Advisory: it does not block you |+| **Browsentic Bridge** | `%USERPROFILE%\.browsentic\cli` holds the version this app carries | **Install** copies it there, writes the `browsentic.exe` launcher to `%USERPROFILE%\.browsentic\bin`, and registers it with your browsers so they can start it |+| **A browser** | Chrome, Edge, Brave, Vivaldi, Opera, Chromium or Firefox is installed | **Get Chrome** opens the download page. Advisory: it does not block you || **An AI agent** | One of `claude`, `codex`, `agy`, `vibe`, `grok`, `cursor-agent`, `qwen` or `opencode` is on your `PATH` | **Install Claude Code** runs `npm install --global @anthropic-ai/claude-code`. Advisory |-**Set up everything** installs the first three in one click. A browser and an agent are yours to-choose, so each has a button of its own. When everything required is in place the app moves on by+**Set up everything** installs Node and the Bridge in one click. A browser, the extension and an+agent are yours to choose, so each has a button of its own. When everything required is in place the app moves on byitself.Claude Code on Windows also needs [Git for Windows](https://git-scm.com/downloads/win), which it@@ -56,33 +56,42 @@ runs its shell commands through.## The window-The tabs float at the top; Ctrl+1 to Ctrl+8 switch between them. Ctrl+Shift+D turns the daemon+The tabs float at the top; Ctrl+1 to Ctrl+8 switch between them. Ctrl+Shift+D turns the Bridgeon or off, Ctrl+Shift+R restarts it, and Ctrl+Shift+P gets a new pairing code.| Tab | What you do there || --- | --- |-| **Overview** | Turn the daemon on and off with the power button, restart it, see its address, version and whether the extension is connected and in sync. Copy the extension's folder, or open `chrome://extensions` in your browser with the folder already on the clipboard |-| **Browsers** | Get a [pairing code](pair.md) with a live countdown, see every paired browser, unpair one or all |+| **Overview** | Turn Browsentic Bridge on and off with the power button, restart it, see its address and version. One row per browser: where its extension comes from, whether it is connected, and a button that adds it from the store. The unpacked folder sits behind **Load it unpacked instead** |+| **Browsers** | Get a [pairing code](pair.md) with a live countdown, see every paired browser and the store its extension came from, unpair one or all || **Agents** | See which agent CLIs are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs || **Skills** | Every [skill](features/skills.md) the router can see and which folder it came from || **Activity** | Your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured || **Logs** | `%USERPROFILE%\.browsentic\daemon.log`, followed live |-| **Settings** | Light, dark or system appearance for this window; whether the daemon starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall |+| **Settings** | Light, dark or system appearance for this window; whether the Bridge starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall || **About** | Who makes Browsentic, a GitHub star, every version on this computer with a copy button, **Report a bug** (GitHub's issue form with those versions filled in — nothing is sent until you submit it), and links to the guide, this page, [troubleshooting](troubleshooting.md) and the release notes. **Run the checks again** reruns the first-run checks |-The Browsentic icon in the notification area shows the daemon's state and has the same on, off and+The Browsentic icon in the notification area shows the Bridge's state and has the same on, off andrestart, and a left click opens the window.**Closing the window does not stop anything.** The app stays in the notification area, and the-daemon is a background process of its own, so the side panel and any MCP client keep working with+Bridge is a background process of its own, so the side panel and any MCP client keep working withthe app closed or quit.-## Loading the extension+## Adding the extension-Browsers load an unpacked extension only by hand. **Extensions in Google Chrome** (or Edge, or-Brave) on the Overview tab opens `chrome://extensions` with the extension's folder on the-clipboard. Turn on **Developer mode**, press **Load unpacked**, click the folder picker's address-bar, paste, and press Enter. Then open the Browsentic popup and paste a pairing code.+**Overview** lists the browsers on your computer, one row each, with where the extension comes from+and whether it is connected. A browser without it has a button — **Add to Chrome**, **Add to Edge**,+**Get the Firefox add-on** — that opens its store page in that browser and shows a pairing code.+Press the store's button, click Browsentic in the toolbar, enter the code, and the row turns+**Connected**. Edge installs from the Chrome Web Store until its own listing is published; the app+tells you to press **Allow extensions from other stores** first.++**Load it unpacked instead**, under the rows, is for a browser that cannot reach a store or for an+unreleased build. It writes the extension to `%USERPROFILE%\browsentic\extension\chrome-mv3`, and+**Extensions in Google Chrome** (or Edge, or Brave) opens `chrome://extensions` with that folder on+the clipboard. Turn on **Developer mode**, press **Load unpacked**, click the folder picker's address+bar, paste, and press Enter. **Reload needed** shows on that row when the folder holds a newer build+than the browser has loaded.## `browsentic` in your terminal@@ -105,9 +114,9 @@ one command, not two that can drift apart. The Settings tab says so when it findThe app asks GitHub for a newer release when it opens and every few hours after. When one is out,a card appears at the top of **Overview** (and in Settings) with **Update now**: it downloads the newinstaller, checks it carries a signature from Browsentic's release key, runs it, and reopens the app,-which replaces the command and the extension and restarts the daemon. Then press ↻ on the Browsentic-card at `chrome://extensions`, which is the one step no installer can do for you. **Check for-updates** on the same card asks again on the spot.+which replaces the Bridge and restarts it. The extension updates itself from its store; only an+unpacked copy needs ↻ on its card at `chrome://extensions`, and the app says so. The two don't have+to be the same version. **Check for updates** on the same card asks again on the spot.If an update fails nothing is changed, and the card hands you the PowerShell line, which installsthe same release.@@ -117,11 +126,11 @@ the same release.## Uninstall**Settings → Uninstall…** runs [`browsentic uninstall`](../reference/cli.md#uninstall): it unpairs-every browser, stops the daemon and removes `%USERPROFILE%\.browsentic` and `%USERPROFILE%\browsentic`,-optionally keeping your skills. Remove the Browsentic card at `chrome://extensions` first. Then-uninstall the app itself in **Settings › Apps › Installed apps**.+every browser, stops the Bridge and removes `%USERPROFILE%\.browsentic` and `%USERPROFILE%\browsentic`,+optionally keeping your skills. Remove Browsentic from each browser first (right-click its toolbar+icon → **Remove**). Then uninstall the app itself in **Settings › Apps › Installed apps**.-Uninstalling only the app, from Installed apps, stops the daemon and takes `browsentic` off your+Uninstalling only the app, from Installed apps, stops the Bridge and takes `browsentic` off your`PATH`, and leaves your pairing, settings and skills where they are, as dragging the macOS app tothe Trash does.diff --git a/docs/internals/README.md b/docs/internals/README.mdindex 951a655..f241de7 100644--- a/docs/internals/README.md+++ b/docs/internals/README.md@@ -13,7 +13,7 @@ Read in order, these pages follow a request through all of them:| | || --- | --- || **1.** [Overview](overview.md) | The four processes, and why a Manifest V3 extension forces a daemon |-| **2.** [Transport](transport.md) | Ports, the `Origin` gate, the mutual pairing handshake, protocol versioning |+| **2.** [Transport](transport.md) | Ports, the `Origin` gate, the mutual pairing handshake, the protocol window || **3.** [The action registry](registry.md) | One definition compiled into two bundles; names, drift detection, reserved actions || **4.** [Request path](request-path.md) | Path A — an MCP client's tool call reaching the page || **5.** [Inside the extension](extension.md) | Background vs content script, self-healing injection, tab scoping |@@ -24,6 +24,7 @@ Read in order, these pages follow a request through all of them:| **10.** [Contributing](contributing.md) | Build topology, the checks, and adding a capability || **11.** [The macOS app](mac-app.md) | What is native, what stays in the daemon, and how the payload is laid down || **12.** [The Windows app](windows-app.md) | The same app in Tauri and React, the launcher, the PATH, and how it updates |+| **13.** [Store listings](stores.md) | The Chrome Web Store and Edge Add-ons IDs, submitting an update, and every field the dashboards ask for |Looking for an error code? [reference/errors.md](../reference/errors.md).diff --git a/docs/internals/mac-app.md b/docs/internals/mac-app.mdindex 59c86fe..1b2eec3 100644--- a/docs/internals/mac-app.md+++ b/docs/internals/mac-app.md@@ -38,10 +38,14 @@ package’s layout — `dist/cli.js`, `dist/daemon-main.js`, `skills/`, `extensi[Payload.swift](../../src/mac/Sources/Browsentic/Core/Payload.swift) copies that to`~/.browsentic/cli` with a directory swap and writes `.browsentic-app.json` beside it.`installKind()` in [npx.ts](../../src/daemon/npx.ts) reads that marker and answers `app`, which-makes `upgradeCli()` step aside: an app install is only ever replaced by a newer app. The-**extension** is still installed by `browsentic setup`, file by file, for the reasons-[install.ts](../../src/daemon/install.ts) gives — and to the same path, for the reasons-[paths.ts](../../src/daemon/paths.ts) gives.+makes `upgradeCli()` step aside: an app install is only ever replaced by a newer app. After the+copy, the app runs `browsentic setup --no-pair --no-open --no-wait --json`, which registers the+native host with every browser and asks nothing. The extension comes from each browser's store:+the Overview rows read `browsentic browsers --json` and their buttons run+`setup --browser <id> --no-wait --json`, which opens the store page in that browser and returns the+pairing code. An unpacked **extension**, when someone asks for one, is written by+`setup --unpacked`, file by file, for the reasons [install.ts](../../src/daemon/install.ts) gives —+and to the same path, for the reasons [paths.ts](../../src/daemon/paths.ts) gives.## PATHdiff --git a/docs/internals/state.md b/docs/internals/state.mdindex 06e58dd..eefdbd2 100644--- a/docs/internals/state.md+++ b/docs/internals/state.md@@ -22,7 +22,7 @@ Nothing lives in the repository.└── runtime/node/ desktop apps only, and only when the computer had no Node 20+: a private copy from nodejs.org~/browsentic/ (paths configurable)-├── extension/chrome-mv3/ the unpacked extension `browsentic setup` installs+├── extension/chrome-mv3/ the unpacked extension `browsentic setup --unpacked` writes, when asked for├── skills/ panel uploads + activated site maps│ ├── acme-com/SKILL.md│ └── .staging/ maps awaiting review — unreadable to the loader@@ -38,7 +38,7 @@ Nothing lives in the repository.| `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 || `schedules.json` | The Schedules tab, `browsentic tasks` | At most 25 tasks. The daemon re-reads it every minute, so an edit from the CLI lands without a restart. Transcripts stay in the extension: the last three runs of each task |-| `native-host/` | `browsentic setup` | A launcher that runs this CLI with the `PATH` setup saw. Each browser gets a manifest in its own `NativeMessagingHosts` folder (a registry key on Windows) naming the extension origins allowed to use it; pairing adds the new one. `browsentic uninstall` removes both |+| `native-host/` | `browsentic setup` | A launcher that runs this CLI with the `PATH` setup saw. Each browser gets a manifest in its own `NativeMessagingHosts` folder (a registry key on Windows) naming the extension origins allowed to use it: both store listings always, the unpacked folder, and each paired browser. Pairing adds the new one, and the Bridge rewrites them every time it starts. `browsentic uninstall` removes both || `stopped` | `browsentic stop` and `restart` | While it exists the helper starts no daemon, so a paired browser cannot undo a stop. The next daemon to start removes it || `cli/`, `bin/`, `runtime/` | The [macOS](../guide/mac-app.md) or [Windows](../guide/windows-app.md) app | 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 |@@ -89,7 +89,7 @@ timers — none of what a page reported about itself outlives the browser that r## Relocating`BROWSENTIC_HOME` moves `~/.browsentic` wholesale. `screenshotDir` and `skillsDir` in config move-those two `~/browsentic` subdirectories independently, and `browsentic setup --dir` installs the+those two `~/browsentic` subdirectories independently, and `browsentic setup --unpacked --dir` installs theextension somewhere else.---diff --git a/docs/internals/stores.md b/docs/internals/stores.mdnew file mode 100644index 0000000..07d1a91--- /dev/null+++ b/docs/internals/stores.md@@ -0,0 +1,164 @@+# Store listings++The extension is published on the Chrome Web Store and submitted to Edge Add-ons; Firefox gets a+signed `.xpi` on every GitHub release instead (see the [Firefox section of the install+guide](../guide/install.md#firefox)). This page is everything a store submission asks for, in the+order the dashboards ask for it, so an update is a matter of pasting.++---++## The listings++| Store | Identity | Address |+| --- | --- | --- |+| Chrome Web Store | `npmocgldfflonjjmdadmdefpnfagnjmp` | [chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp](https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp) — published at 0.8.0 on 4 October 2026 |+| Edge Add-ons | CRX ID `cbkjhkgjcpihokphhdkbahilpcjojpdc` (Partner Center Store ID `0RDCKBB847NN`) | None until Microsoft publishes it; certification of 0.8.0 is under way |+| Firefox | `[email protected]` | `browsentic-<version>-firefox.xpi` on each release, signed on the unlisted channel |++The IDs are fixed for good, and three places depend on them:++- [`src/lib/stores.ts`](../../src/lib/stores.ts) names them, and says where each browser gets the+ extension. Until `EDGE_ADD_ONS.url` is set, Edge is sent to the Chrome Web Store.+- The native messaging host lets both store IDs start Browsentic Bridge whether or not they have+ paired yet ([native-host.ts](../../src/daemon/native-host.ts)).+- The Bridge names each session's source from its origin: a store ID, a `moz-extension://` origin,+ or anything else, which is an unpacked copy.++A store copy keeps the extension's storage, and so its install id and session key, under the+store's ID. Moving from the unpacked folder to a store copy is therefore a new extension, paired+once more.++---++## Submitting an update++1. **Unfreeze the extension.** While a build is in review or freshly published, the extension does+ not change: [`src/extension/store-lock.json`](../../src/extension/store-lock.json) holds a hash+ of every file in it, and `node scripts/extension-lock.ts` fails CI and the release on any+ difference. The pull request that changes the extension runs `yarn build`, then+ `node scripts/extension-lock.ts write`.+2. **Pick a version above every one spent.** The Chrome Web Store has seen 0.7.11 and 0.8.0, and+ Edge Add-ons 0.8.0. A store refuses a number it has already accepted, even for a build it+ rejected.+3. **Check the permissions** against the table below. A new permission needs a line here before it+ goes up, and a permission nothing uses comes out (`activeTab` is the current candidate).+4. **`yarn zip`**, and upload `dist/browsentic-<version>-chrome.zip` to both stores. The Edge zip is+ the same file: only Firefox branches the code, and Edge is told apart at run time.+5. **Keep the window.** A store copy updates on the browser's schedule, so a new extension must+ still work with the Bridge already out there, and a new Bridge with the extension already out+ there. The rule is in [transport.md](transport.md#protocol-version): additive changes bump+ `SOCKET_PROTOCOL_VERSION` and are sent only to a peer that speaks them.++**The Chrome Web Store** can hold an approved build: untick *publish automatically after review*+and press **Publish** within the window it gives. **Edge Add-ons** cannot: passing certification+(up to seven business days) publishes it. Set visibility to **Hidden** to keep it out of search+while the link still installs it.++---++## Listing text++**Category** Developer Tools · **Language** English · **Mature content** No ·+**Website** https://browsentic.com · **Support** https://github.com/imshaikot/browsentic/issues ·+**Privacy policy** https://browsentic.com/privacy/++The summary under the name is the manifest's `description`. The description field:++```text+Browsentic gives your browser a superpower: an AI agent in the side panel that works in the browser you already use, with your tabs, your logins and your sessions. Free, open source, and no API key, no subscription, no account.++Open the side panel, say what you want done, and watch it happen in your own tabs. The thinking is done by the AI agent you already have on your computer, such as Claude Code or Codex, so there is nothing new to sign up for.++WHAT IT DOES+• Reads the page as structure, not pixels, then clicks, types, scrolls, fills in forms and moves between tabs the way you would+• Works in your real, logged-in browser, so it reaches the sites you use without you handing over a password+• Show it a job once and replay it later, or schedule it to run on its own, once or on repeat+• Hands-free mode: talk to it instead of typing+• Writes small tools for sites you use often. You read and approve each one, keep it, and can let it run by itself on every visit+• A Profile for the details forms keep asking for, plus standing instructions for every task, so it fills things in without guessing+• Attach a file and ask about it alongside the page+• Several tasks in several tabs at once++SAFE BY DESIGN+• Connects to nothing until you pair it with a one-time code+• Stops and asks you before anything that counts+• Passwords, keys and tokens are swapped for a sealed placeholder, so the model never sees them+• Sites you block are off-limits to every agent, enforced in the browser+• No Browsentic server and no analytics. Page content goes only to the agent you chose and its model provider++WHAT YOU NEED+Browsentic is two pieces plus the AI you already use: this extension, and Browsentic Bridge on your computer, which starts your agent and keeps everything local.+• On macOS or Windows: install the Browsentic app from browsentic.com, which sets everything up+• On Linux, or without the app: Node.js 20 or newer, then run: npx browsentic@latest setup+• An agent CLI signed in on your computer, such as Claude Code, Codex, or one of the others listed at browsentic.com+Then click Browsentic in the toolbar, enter the pairing code once, and open the side panel.++OPTIONAL: DRIVE IT FROM A TERMINAL+The same paired browser can also be driven from an MCP client such as Claude Code, Cursor or Zed. This is optional. The side panel needs none of it.++OPEN SOURCE+Apache 2.0. Source, docs and issues: https://github.com/imshaikot/browsentic+Website and install guide: https://browsentic.com+Privacy policy: https://browsentic.com/privacy/+```++Edge Add-ons wants the description at 250 characters or more (this is well over), a 300×300 logo,+and reuses the same screenshots. The images — five 1280×800 screenshots, a 440×280 small tile and a+1400×560 marquee — are rendered outside the repository.++---++## Privacy tab++**Single purpose**++> Browsentic is an AI agent in the browser's side panel. The user describes a task in words or by+> voice, and the extension carries it out in their own tabs (reading pages, filling in forms,+> clicking through flows), powered by an AI agent the user already runs on their own computer.++**Permission justifications**++| Permission | Why |+| --- | --- |+| `storage` | Keeps the user's conversations, settings, saved tools and pairing state in the extension's own storage on their computer. |+| `unlimitedStorage` | Recordings of flows the user shows it, attached files and screenshots are kept locally and can exceed the default storage quota. |+| `activeTab` | Gives access to the tab the user is on when they open Browsentic from the toolbar button or the right-click menu. |+| `contextMenus` | Adds one "Open Browsentic" item to the right-click menu, which opens the side panel. |+| `alarms` | Wakes the service worker to reconnect to Browsentic Bridge on the user's computer, to start the user's scheduled tasks on time, and to run timers and page monitors the user asked for. |+| `scripting` | Reads and acts on the pages the user asks about: finding elements, filling in fields, clicking and extracting text. |+| `notifications` | Tells the user when a scheduled task or a timer they set has finished, or when a task needs their approval. |+| `downloads` | Saves a file the user asked the agent to download, and lists what it downloaded so it can hand the file back in the conversation. |+| `nativeMessaging` | Starts Browsentic Bridge, Browsentic's own companion on the user's computer, when it is not running. It talks only to Browsentic's native host. |+| `sidePanel` | The side panel is Browsentic's main interface: the user types or speaks a task there and watches each step as it happens. |+| `debugger` | Used where a page's own scripts would otherwise block an action: trusted clicks and key presses, working inside cross-origin frames, and pages whose Content Security Policy blocks injected scripts. It attaches only to the tab a task is working on, and Chrome shows its standard banner while attached. |+| `offscreen` | Hands-free mode listens for the user's voice through an offscreen document, so it keeps working after the side panel is closed. |+| `userScripts` | Runs a saved tool that the user has reviewed and approved on each visit to its site. It works only after the user turns on Allow User Scripts for Browsentic. |+| Host permission `<all_urls>` | Browsentic works on whatever site the user is on, so it needs to read and act on any page the user asks it to. It does nothing on a page until the user gives it a task there, apart from features the user turns on themselves (a page monitor, a recording, or a saved tool set to run on every visit). |++The `commands` key (keyboard shortcuts) needs no justification.++**Remote code:** *Yes*, with this justification:++> Browsentic never downloads code from a server. It runs JavaScript in a page in only two ways, both+> through APIs Chrome documents for this: (1) through chrome.debugger, the user's own AI agent,+> running on their computer, can write a short script for the page it is working on; the user can+> review it, and by default it runs only after they press Allow. (2) Through chrome.userScripts, a+> script the user has reviewed and saved runs on each visit to its site, only after the user turns+> on Allow User Scripts.++**Data usage:** tick *Personally identifiable information* (the Profile), *Authentication+information* (passwords are sealed, but the extension handles them), *User activity* (recordings)+and *Website content*; leave the rest unticked, and tick all three certifications underneath.++---++## Test instructions++```text+Browsentic needs Browsentic Bridge on the computer and an AI agent CLI; the extension alone shows "offline".+1. On macOS or Windows, install the Browsentic app from https://browsentic.com/install/ . On Linux, install Node.js 20 or newer and run: npx browsentic@latest setup+2. Install and sign in to an agent CLI, such as Claude Code or Codex.+3. The app, or setup, shows a pairing code. Click Browsentic in the toolbar and enter it. (Skip any steps for loading an unpacked copy: the extension is already installed from the store.)+4. Open the side panel on any web page and type a task, for example: Summarise what this page says.+Demo videos of the full flow: https://browsentic.com/demos/+```diff --git a/docs/internals/transport.md b/docs/internals/transport.mdindex c904085..e7d6809 100644--- a/docs/internals/transport.md+++ b/docs/internals/transport.md@@ -68,7 +68,7 @@ The extension connects to nothing until you pair it.three ports, and sends `hello` — which names *which* secret it holds and a fresh nonce, never thesecret itself.3. The daemon answers `challenge` with a nonce of its own. Both sides now share a transcript:- protocol version, extension version, manifest hash, and the two nonces. The manifest hash+ the protocol version the `hello` claimed, extension version, manifest hash, and the two nonces. The manifest hashnames the tool list this build offers — a Chromium build's or a Firefox build's, which leavesoff the nine tools that need Chrome's debugger. The daemon knows both lists and serves the onethe hash names; an unknown hash is a drifted build, which is asked for its list and served@@ -82,7 +82,8 @@ The extension connects to nothing until you pair it.distinct, so an impostor cannot reflect the extension's own proof back at it.6. On pairing, the daemon mints a **session key** (32 random bytes) bound to the **install id**the `hello` carried — a UUID the extension mints once per browser profile. The origin cannot- name a browser: every Chromium browser loading the same unpacked folder presents the same one.+ name a browser: every browser installing from the same store, or loading the same unpacked+ folder, presents the same one.A session paired before install ids existed is found by its origin and claimed by whicheverbrowser proves its key. The daemon returns the key XORed with a keystream derived from the same secret, so the long-lived credentialnever crosses the wire in the clear. It survives browser and daemon restarts and dies only when@@ -111,8 +112,25 @@ dialling — but it never deletes the stored key. Only pairing again or `disconn## Protocol version-Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **21**). A mismatch closes the socket-with an explicit reason instead of letting two incompatible frame vocabularies talk past each other.+Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **22**). They used to have to match+exactly. A store copy updates when its browser decides to, not when the daemon does, so the+extension and the daemon are now routinely a version apart, and the daemon takes a **window**:++- It lets in any extension whose `hello` claims `MIN_EXTENSION_PROTOCOL` (22) or more, newer than+ itself included, and builds the transcript from the number the `hello` claimed, so the proofs+ verify across versions. Older ones are refused with `protocol version mismatch: …`, the words an+ extension before 0.8 already reads as a refusal not worth retrying.+- A `hello` may carry `minDaemonProtocol`, the oldest daemon that extension works with. A daemon+ below it refuses with `daemon too old: …`.+- `welcome` carries the daemon's own `protocolVersion`, so a newer extension knows what not to+ send. A `welcome` without one comes from a daemon before 0.8, which speaks 22 or less.++**The rule for changing it.** A change a peer can do without — a new frame, a new optional field —+bumps `SOCKET_PROTOCOL_VERSION`, and the new frame is sent only to a peer whose `hello` (or+`welcome`) says it speaks that number. Anything the daemon does not know, it leaves unanswered. Only+a change neither side can do without raises a minimum. A refusal must never strand a browser: the+v0.8.0 store build unpairs on any refusal and does not retry, so no daemon may refuse protocol 22+until a store build that retries has replaced it.---diff --git a/docs/reference/cli.md b/docs/reference/cli.mdindex 00b96cd..9e2a45c 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -4,9 +4,10 @@browsentic <command>```-With no command it prints usage. Most commands start the daemon if one is not already running;-`status`, `stop`, `logs`, `token`, `tools`, `skills`, `approvals`, `downloads` and `uninstall` do-not — an uninstall that started a daemon would be absurd.+With no command it prints usage. `browsentic` is Browsentic Bridge's command: the half of+Browsentic that runs on your computer. Most commands start the Bridge if it is not already running;+`status`, `browsers`, `stop`, `logs`, `token`, `tools`, `skills`, `approvals`, `downloads` and+`uninstall` do not — an uninstall that started one would be absurd.---@@ -14,32 +15,44 @@ not — an uninstall that started a daemon would be absurd.| Command | Does || --- | --- |-| `browsentic setup` | Install the extension, start the daemon, print a pairing code |-| `browsentic update` | Pull the newest build: the command itself first, then the extension, then restart the daemon |-| `browsentic uninstall` | Stop the daemon and remove everything Browsentic wrote |+| `browsentic setup` | Start the Bridge, then add the extension to a browser and pair the two |+| `browsentic update` | Pull the newest Bridge, restart it, and refresh the unpacked folder if you load one |+| `browsentic browsers` | List the browsers on this computer, where each gets the extension, and which are connected |+| `browsentic uninstall` | Stop the Bridge and remove everything Browsentic wrote |-`setup` writes the extension to `~/browsentic/extension/chrome-mv3` and leaves you two steps: load-that folder at `chrome://extensions` with Developer mode on, and paste the code into the popup.+On a terminal, `setup` checks your agent and asks which browser should get the extension. It opens+that browser's store page in it — the Chrome Web Store for Chrome, Brave, Arc, Vivaldi, Opera,+Chromium and, until its own listing is published, Edge; the signed add-on for Firefox — prints a+pairing code, and waits up to five minutes for the browser to connect. Ctrl-C stops the wait and+undoes nothing. With no terminal and no `--browser`, it asks nothing: it prints where each browser+gets the extension and a code, so a script or an app never hangs on it.-The install path never carries a version, deliberately. Chrome derives an unpacked extension's ID-from the absolute path of its directory, and the browser keeps the extension's storage — the-install id and the session key with it — under that ID, so a versioned path would unpair the browser-on every update.+Every run also registers the Bridge with each browser it finds, so the browser can start it when it+is down (`wake-up:` in `status`).| Flag | Does || --- | --- |-| `--dir <path>` | Install somewhere else. Needed for Flatpak or Snap browsers, which cannot read `~/browsentic` without a filesystem grant |-| `--no-pair` | Install and start the daemon, mint no code |-| `--force` | Rewrite every file even when the installed build already matches |-| `--browser <name>` | `chrome` (the default) or `firefox`. Firefox has no folder to load: the command starts the daemon, prints the link to the signed add-on for this same version — and says so if Mozilla has not attached it to the release yet — then the pairing code. `update --browser firefox` only restarts the daemon, because Firefox updates the add-on on its own |-| `--no-self-update` | Install what this copy carries, without asking the registry whether a newer one exists |-| `--json` | Machine-readable result. Progress goes to stderr, so stdout stays parseable |+| `--browser <name>` | `chrome`, `edge`, `brave`, `arc`, `vivaldi`, `opera`, `chromium` or `firefox`: skip the question. For Firefox it also says when Mozilla has not attached the signed add-on to this version's release yet |+| `--unpacked` | Write the extension to `~/browsentic/extension/chrome-mv3` and print the steps to load it at the browser's extensions page, for a browser that cannot reach a store or for an unreleased build |+| `--dir <path>` | With `--unpacked`, write it somewhere else. Needed for Flatpak or Snap browsers, which cannot read `~/browsentic` without a filesystem grant. Remembered, so `update` refreshes the same copy |+| `--no-open` | Print the store link instead of opening it |+| `--no-wait` | Print the code and return, instead of waiting for the browser |+| `--no-pair` | Mint no code. `update` passes it |+| `--force` | Rewrite every file of the unpacked folder even when it already matches |+| `--no-self-update` | Run what this copy carries, without asking the registry whether a newer one exists |+| `--json` | Machine-readable result, with every browser's row, as the apps read it. Never asks, never waits |++The unpacked folder is written only when you ask for it, and kept current once it exists: `setup`+and `update` refresh it in place. Its path never carries a version, deliberately. Chrome derives an+unpacked extension's ID from the absolute path of its directory, and the browser keeps the+extension's storage — the install id and the session key with it — under that ID, so a versioned+path would unpair the browser on every update.`setup` and `update` both replace the command itself when the registry has something newer, because-the extension ships *inside* the package — a stale CLI installs a stale extension and says-"already current". Under `npx` that lasts as long as the cache does, which is what made `update`-look like it did nothing. A pinned `npx browsentic@<version>` is never upgraded past, and a source-checkout is told rather than touched.+a stale command runs a stale Bridge and lays down a stale unpacked folder, and says "already+current". Under `npx` that lasts as long as the cache does, which is what made `update` look like it+did nothing; `npx browsentic@latest` asks every time. A pinned `npx browsentic@<version>` is never+upgraded past, and a source checkout is told rather than touched.### Uninstall@@ -49,10 +62,9 @@ checkout is told rather than touched.| `--yes` / `-y` | Skip the confirmation. Required when stdin is not a terminal || `--keep-skills` | Leave `skills/` behind — site maps and hand-written notes have no other copy |-It removes the daemon (found by probing 8765–8767, so an orphan whose lockfile was deleted is still+It removes the Bridge (found by probing 8765–8767, so an orphan whose lockfile was deleted is stillcaught), `~/.browsentic`, `~/browsentic`, and every `~/.npm/_npx/*` directory holding a copy of the-package. It names, but will not touch, the extension card at `chrome://extensions`, the command-itself, your MCP client's entry, and any directory you moved with `screenshotDir`, `downloadDir` or+package. It names, but will not touch, the extension in each browser, the command itself, your MCP client's entry, and any directory you moved with `screenshotDir`, `downloadDir` or`skillsDir`.See [guide/install.md](../guide/install.md) and [guide/maintenance.md](../guide/maintenance.md).@@ -95,8 +107,8 @@ configurations written against the older name keep working.| Command | Does || --- | --- |-| `browsentic status` | Daemon and extension state, the installed build, manifest sync, pairing count |-| `browsentic logs` | Print the daemon log (`~/.browsentic/daemon.log`) |+| `browsentic status` | The Bridge, which browsers can start it, the agent, and one row per paired browser with its extension version, its store and whether it is connected; flags an unpacked copy that needs ↻ and two copies answering in one browser |+| `browsentic logs` | Print the Bridge's log (`~/.browsentic/daemon.log`) || `browsentic tools` | Print the bundled tool manifest as JSON. **No browser needed** || `browsentic skills` | Every skill the router can see, tagged `bundled`, `user` or `uploaded` || `browsentic approvals` | The "always on this site" grants |@@ -115,9 +127,9 @@ configurations written against the older name keep working.| Command | Does || --- | --- |-| `browsentic start` | Bring the background daemon up, if it is not already |-| `browsentic stop` | Stop the background daemon, whichever of 8765–8767 is answering. A paired browser leaves it stopped until `browsentic start`, or an MCP client, starts it |-| `browsentic restart` | Stop the daemon and bring up a fresh one |+| `browsentic start` | Bring the Bridge up in the background, if it is not already |+| `browsentic stop` | Stop the Bridge, whichever of 8765–8767 is answering. A paired browser leaves it stopped until `browsentic start`, or an MCP client, starts it |+| `browsentic restart` | Stop the Bridge and bring up a fresh one || `browsentic --version` / `-v` | Print the version || `browsentic help` / `--help` / `-h` | Usage |diff --git a/scripts/release-notes.mjs b/scripts/release-notes.mjsindex f8272be..9bf75d0 100644--- a/scripts/release-notes.mjs+++ b/scripts/release-notes.mjs@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';import { writeFileSync } from 'node:fs';const REPO = 'imshaikot/browsentic';+const CHROME_WEB_STORE = 'https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp';const SECTIONS = [['feat', 'Features'],@@ -91,6 +92,15 @@ function renderNotes(version, commits, prevTag) {lines.push('### Install','',+ 'Browsentic is two pieces plus the AI you already use. Install the first two in either order, then pair them once with a code.',+ '',+ '**1. The extension**, in your browser:',+ '',+ `- **Chrome, Edge, Brave, Arc, Vivaldi, Opera** — [Chrome Web Store](${CHROME_WEB_STORE}). In Edge, press **Allow extensions from other stores** first. It updates itself.`,+ `- **Firefox 140 or newer** — \`browsentic-${version}-firefox.xpi\` below, signed by Mozilla. Open it in Firefox and accept both prompts; it updates itself.`,+ '',+ '**2. Browsentic Bridge**, on your computer. It runs your agent and keeps everything local.',+ '','**macOS** — installs the app, and the app installs everything else, Node included:','','```sh',@@ -115,24 +125,21 @@ function renderNotes(version, commits, prevTag) {`npx browsentic@${version} setup`,'```','',- 'That installs the extension, starts the daemon and prints a pairing code. Then load the folder',- 'it names at `chrome://extensions` with **Developer mode** on, and paste the code into the popup.',+ 'It asks which browser should get the extension, opens its store page there, and prints a pairing code.',+ 'The apps do the same from their Overview tab.','',- '**Firefox** — 140 or newer:',+ '**3. An agent CLI you are signed in to** — Claude Code, Codex, or another supported one.','',- '```sh',- `npx browsentic@${version} setup --browser firefox`,- '```',+ 'Then click Browsentic in the toolbar and enter the pairing code, once.','',- `That prints the link to \`browsentic-${version}-firefox.xpi\` below, signed by Mozilla, and a pairing code.`,- 'Open the link in Firefox, accept both prompts, and paste the code into the popup. Firefox updates the',- 'add-on by itself from then on. If the command says the file is not attached yet, Mozilla is still signing it.',+ 'Already running an older version? The Mac and Windows apps offer the update on their Overview tab, and',+ '`npx browsentic@latest update` updates the Bridge from a terminal. Your browser stays paired, and the',+ 'extension and the Bridge do not have to be the same version. Only an unpacked copy needs ↻ on its card.','',- 'Already running an older version? `npx browsentic update` refreshes the command and the',- 'extension in place and keeps your browser paired. Press ↻ on the Browsentic card afterwards;',- 'Firefox needs nothing pressed, and the Mac and Windows apps offer the update on their Overview tab.',+ '<details><summary>Load it unpacked, from the zips, or from source</summary>','',- '<details><summary>From the zips, or from source</summary>',+ `For a browser that cannot reach a store: \`npx browsentic@${version} setup --unpacked\` writes the extension to a`,+ 'folder and prints the steps to load it with **Developer mode** on.','',`The \`-chrome.zip\` and \`-firefox.zip\` below are the same builds, for loading by hand. Release Firefox`,'installs only the signed `.xpi`; the zip is for Developer Edition or Nightly.',@@ -140,7 +147,7 @@ function renderNotes(version, commits, prevTag) {'```sh',`git clone --branch v${version} https://github.com/${REPO}.git`,'cd browsentic && yarn setup && yarn daemon:link',- 'browsentic setup',+ 'browsentic setup --unpacked','```','','</details>',diff --git a/scripts/setup.mjs b/scripts/setup.mjsindex 0b6002f..4430136 100644--- a/scripts/setup.mjs+++ b/scripts/setup.mjs@@ -49,7 +49,7 @@ STEPS.forEach(([label, args], i) => {console.log(`\x1b[32m✓ Extension built\x1b[0m dist/chrome-mv3 — load it unpacked at chrome://extensions, Developer mode on-\x1b[32m✓ Daemon built\x1b[0m src/daemon/dist+\x1b[32m✓ Bridge built\x1b[0m src/daemon/dist — the daemon, the CLI and the MCP serverTwo steps are left. Both reach outside this directory, so they stay separate:diff --git a/src/daemon/README.md b/src/daemon/README.mdindex abca5e0..d5e8e61 100644--- a/src/daemon/README.md+++ b/src/daemon/README.md@@ -1,29 +1,34 @@# browsentic-Hand your real, logged-in browser to the AI agent you already run.+This is **Browsentic Bridge**, the half of Browsentic that runs on your computer.-Browsentic is a browser extension plus a local daemon. The extension opens a side panel beside-whatever tab you are on; the daemon runs on loopback and wakes the agent CLI you already have-installed. There is no hosted relay, no API key, and no headless browser — it drives the tab you+Browsentic is your browser's superpower: a side panel that drives your real, logged-in browser with+the AI agent you already use. The extension opens the panel beside whatever tab you are on; the+Bridge runs on loopback and wakes the agent CLI you already have installed. It is free and open+source, with no hosted relay, no API key, no account and no headless browser — it drives the tab youare already signed in to.-This package carries both halves: the daemon, and the extension build that `browsentic setup`-installs onto disk.-## Install-```sh-npx browsentic setup-```+Browsentic is two pieces plus the AI you already use:++1. **The extension**, in your browser: from the+ [Chrome Web Store](https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp)+ for Chrome, Edge, Brave, Arc, Vivaldi and Opera, or the+ [signed add-on](https://browsentic.com/download/firefox) for Firefox.+2. **Browsentic Bridge**, this package:-That installs the extension, starts the daemon and prints a pairing code. Two steps are left, and-both happen inside the browser, so only you can do them:+ ```sh+ npx browsentic@latest setup+ ```-1. Open `chrome://extensions`, turn on **Developer mode**, press **Load unpacked**, and choose the- folder the command printed (`~/browsentic/extension/chrome-mv3`).-2. Open the Browsentic popup and paste the pairing code.+ It starts the Bridge, asks which browser should get the extension, opens its store page there,+ prints a pairing code and waits for the browser to connect. On macOS and Windows an app does the+ same from a window: see [browsentic.com/install](https://browsentic.com/install/).+3. **An agent CLI you're signed in to**: Claude Code, Codex, or another supported one.-Then open the side panel and say what you want.+Click Browsentic in the toolbar, enter the pairing code once, then open the side panel and say what+you want.To update later:@@ -31,30 +36,32 @@ To update later:npx browsentic@latest update```-The extension installs to a stable path on purpose, so an update keeps the same extension ID and-your browser stays paired. Press ↻ on the Browsentic card afterwards to pick up the new build.+The extension updates itself from its store, and the two don't have to be the same version.## Requirements- Node.js 20 or newer-- Chrome, or another Chromium browser-- One agent CLI on your `PATH`: `claude`, `codex` or `agy`+- Chrome, Edge, Brave, Arc, Vivaldi, Opera or another Chromium browser, or Firefox 140 or newer+- One agent CLI on your `PATH`, logged in: `claude`, `codex`, `agy`, `vibe`, `grok`, `cursor-agent`,+ `qwen` or `opencode`## Commands| | || --- | --- |-| `browsentic setup` | install the extension, start the daemon, print a pairing code |-| `browsentic update` | refresh the installed extension and restart the daemon |+| `browsentic setup` | start the Bridge, add the extension to a browser and pair it |+| `browsentic update` | update the Bridge and restart it |+| `browsentic browsers` | the browsers on this computer and where each gets the extension || `browsentic pair` | issue a fresh single-use code |-| `browsentic status` | daemon, extension and agent state |+| `browsentic status` | the Bridge, each paired browser and the agent || `browsentic sessions` | list paired browsers || `browsentic revoke` | unpair one browser, or all of them || `browsentic agent` | choose which agent runs the side panel |-| `browsentic logs` | tail the daemon log |+| `browsentic logs` | tail the Bridge's log || `browsentic mcp` | serve MCP over stdio |-`browsentic help` lists the rest.+`browsentic help` lists the rest. A browser that cannot reach a store can load the extension from+a folder this package carries: `browsentic setup --unpacked`.## Using it from an MCP client@@ -66,11 +73,11 @@ npm i -g browsenticclaude mcp add browsentic -- browsentic mcp```-Any MCP client works: Claude Code, Codex, Cursor, Zed, Claude Desktop. One daemon owns the browser+Any MCP client works: Claude Code, Codex, Cursor, Zed, Claude Desktop. One Bridge owns the browserlink, so several can share the same paired browser at once.Prefer a global install over `npx` here. An `npx` command re-resolves on every client start and can-quietly pull a newer daemon than the extension you have loaded.+quietly start a different Bridge than the one you set up.## Documentation