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(cli): rewrite the install path around npx, and rename the command
Shahriar51ec719418cb
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 0550792..7bb9c61 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -25,9 +25,12 @@ on:push:tags: ['v*']-# The release step needs to write to the Releases API. Nothing else is granted.+# The release step needs to write to the Releases API. id-token is what npm Trusted+# Publishing mints its short-lived credential from, so the publish step needs no secret at+# all and gets a provenance attestation for free.permissions:contents: write+ id-token: write# One tag at a time, and never cancel a run mid-upload: a half-uploaded release is worse# than a slow queue.@@ -69,6 +72,7 @@ jobs:- uses: actions/setup-node@v5with:node-version: 24+ registry-url: 'https://registry.npmjs.org'- name: Install dependencies# Yarn is vendored at the path .yarnrc.yml pins, so this does not depend on whichever@@ -110,6 +114,59 @@ jobs:}done+ - name: Pack and smoke-test the npm tarball+ # `npm pack` runs mcp/scripts/stage-extension.mjs through prepack, so this exercises+ # the same path a maintainer gets locally. Everything below runs against the real+ # tarball rather than the working tree, and it runs before anything is published,+ # because an npm version cannot be taken back.+ run: |+ tarball="$(cd mcp && npm pack --silent)"+ echo "TARBALL=$GITHUB_WORKSPACE/mcp/$tarball" >> "$GITHUB_ENV"++ tar -tzf "mcp/$tarball" | grep -q 'package/extension/chrome-mv3/manifest.json' \+ || { echo "::error::the tarball carries no extension"; exit 1; }+ if tar -tzf "mcp/$tarball" | grep -q '\.map$'; then+ echo "::error::sourcemaps leaked into the tarball"; exit 1+ fi++ mkdir -p /tmp/smoke && cd /tmp/smoke && npm init -y >/dev/null+ npm i --no-audit --no-fund "$GITHUB_WORKSPACE/mcp/$tarball"++ # Zero runtime dependencies. This is the guard that catches someone moving a+ # package back into `dependencies` and quietly restoring the 33 MB install.+ deps=$(ls node_modules | grep -cv '^\.')+ test "$deps" -eq 1 || {+ echo "::error::expected 1 installed package, found $deps"; ls node_modules; exit 1+ }++ npx browsentic --version | grep -qx "$VERSION"+ npx browsentic tools | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const t=JSON.parse(s);if(!Array.isArray(t)||t.length<40)throw new Error("tool manifest looks wrong: "+t.length)})'++ export HOME=/tmp/smoke-home BROWSENTIC_HOME=/tmp/smoke-home/.browsentic+ mkdir -p "$HOME"+ npx browsentic setup --no-pair --json+ node -p "require('$HOME/browsentic/extension/chrome-mv3/manifest.json').version" | grep -qx "$VERSION"++ # The MCP handshake, on both entry points. Bare invocation of the legacy bin must+ # keep serving, and `browsentic mcp` must serve too: an agent run spawns the CLI+ # itself, so a regression here breaks every side-panel run silently.+ cat > /tmp/probe.cjs <<'PROBE'+ const { spawn } = require('child_process');+ const [, , bin, ...args] = process.argv;+ const p = spawn(bin, args, { stdio: ['pipe', 'pipe', 'inherit'] });+ let out = '';+ const finish = (code) => { try { p.kill('SIGKILL'); } catch {} process.exit(code); };+ p.stdout.on('data', (d) => { out += d; if (out.includes('serverInfo')) finish(0); });+ p.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'smoke', version: '0' } } }) + '\n');+ setTimeout(() => { console.error('no serverInfo from ' + bin + ' ' + args.join(' ')); finish(1); }, 20000);+ PROBE+ node /tmp/probe.cjs ./node_modules/.bin/browsentic mcp \+ || { echo "::error::browsentic mcp did not answer initialize"; exit 1; }+ node /tmp/probe.cjs ./node_modules/.bin/browsentic-mcp \+ || { echo "::error::browsentic-mcp lost bare-invocation MCP serving"; exit 1; }++ npx browsentic stop || true+- name: Release notes# Prefers the text `prepare` wrote into the annotated tag, and falls back to reading# the conventional-commit log when the tag carries none.@@ -127,3 +184,32 @@ jobs:"dist/browsentic-$VERSION-firefox.zip" \"dist/browsentic-$VERSION-sources.zip"gh release view "$TAG" --json url -q '"released: " + .url' >> "$GITHUB_STEP_SUMMARY"++ # ---------------------------------------------------------------------------------------+ # Publishing to npm is written but not enabled yet. Two things have to happen first, in+ # this order, and neither can be done from CI:+ #+ # 1. Publish one version by hand from a maintainer's machine. That claims the name and+ # forces someone to install and run the real tarball once before any automation does.+ # 2. Configure the trusted publisher on npmjs.com for imshaikot/browsentic, workflow+ # release.yml. That is what makes `npm publish` work here with no NODE_AUTH_TOKEN.+ #+ # Then delete the `if: false` below. Note that a tag runs this workflow as it existed at+ # the tagged commit, so the change takes effect from the next tag cut after it lands.+ #+ # This is deliberately the LAST step. A GitHub release can be deleted; an npm version+ # cannot — unpublish is restricted to 72 hours and burns the number permanently. Anything+ # that can still fail should have failed by now.+ # ---------------------------------------------------------------------------------------+ - name: Publish to npm+ if: false+ working-directory: mcp+ env:+ NPM_CONFIG_PROVENANCE: true+ run: |+ if npm view "browsentic@$VERSION" version >/dev/null 2>&1; then+ echo "browsentic@$VERSION is already on npm, skipping" >> "$GITHUB_STEP_SUMMARY"+ exit 0+ fi+ npm publish+ echo "published: https://www.npmjs.com/package/browsentic/v/$VERSION" >> "$GITHUB_STEP_SUMMARY"diff --git a/README.md b/README.mdindex cc352fc..9043ffd 100644--- a/README.md+++ b/README.md@@ -18,26 +18,22 @@ Hand your real, logged-in browser to the AI agent you already run. Browsentic is## Quick Start-Clone and build both halves — the extension and the local daemon (requires [Node.js](https://nodejs.org) 20 or newer):+One command installs the extension, starts the local daemon and prints a pairing code (requires [Node.js](https://nodejs.org) 20 or newer):```sh-git clone https://github.com/imshaikot/browsentic.git-cd browsentic-node scripts/setup.mjs+npx browsentic setup```-Load the extension at `chrome://extensions` → **Developer mode** → **Load unpacked** → `dist/chrome-mv3`.+Two steps are left, and both happen inside the browser:-Then put the CLI on your `PATH` and pair your browser:+1. **Load the extension** at `chrome://extensions` → **Developer mode** → **Load unpacked** → the folder it printed (`~/browsentic/extension/chrome-mv3`)+2. **Paste the pairing code** into the Browsentic popup and press **Connect**-```sh-yarn mcp:link-browsentic-mcp pair-```+Then open the side panel and say what you want.-Paste the printed code into the Browsentic popup, press **Connect**, and open the side panel.+You also need one agent CLI on your `PATH` and logged in — `claude`, `codex` or `agy`. Full prerequisites in the [install guide](docs/guide/install.md), which also covers [building from source](docs/guide/install.md#from-source).-You also need one agent CLI on your `PATH` and logged in — `claude`, `codex` or `agy`. Full prerequisites in the [install guide](docs/guide/install.md).+Later, `npx browsentic@latest update` refreshes the extension in place. The install path never changes, so your browser stays paired.## How It Works@@ -51,7 +47,7 @@ You ──speak or type──> Extension ──local WebSocket──> Daemon ─▲ (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 daemon ──> the same browser```</details>diff --git a/components/daemon-link.tsx b/components/daemon-link.tsxindex e5d4e60..c076425 100644--- a/components/daemon-link.tsx+++ b/components/daemon-link.tsx@@ -50,7 +50,7 @@ export function DaemonLink() {<p className="text-[11px] leading-relaxed text-ink-dim">{connected? 'The daemon is driving this browser. Disconnecting revokes the key — you will need a new pairing code.'- : 'Paired, but the daemon is not answering. Start it with browsentic-mcp, or disconnect to pair again.'}+ : 'Paired, but the daemon is not answering. Start it with browsentic, or disconnect to pair again.'}</p><Button variant="outline" size="sm" className="w-full" onClick={disconnect} disabled={busy}>{busy ? <Loader2 className="animate-spin" /> : <Link2Off />} Disconnect@@ -59,7 +59,7 @@ export function DaemonLink() {) : (<><p className="text-[11px] leading-relaxed text-ink-dim">- Run <code className="rounded bg-surface px-1 py-px font-mono text-ink">browsentic-mcp pair</code> in a+ Run <code className="rounded bg-surface px-1 py-px font-mono text-ink">browsentic pair</code> in aterminal and paste the code it prints.</p><form@@ -73,7 +73,7 @@ export function DaemonLink() {value={code}onChange={(event) => setCode(event.target.value)}placeholder="Pairing code"- aria-label="Pairing code from browsentic-mcp pair"+ aria-label="Pairing code from browsentic pair"className="h-8 font-mono text-xs tracking-widest uppercase"autoComplete="off"spellCheck={false}diff --git a/components/greeting.tsx b/components/greeting.tsxindex 1595746..10cedd7 100644--- a/components/greeting.tsx+++ b/components/greeting.tsx@@ -12,7 +12,7 @@ const SUGGESTIONS = [const BLOCKED: Record<StatusBlocker, string> = {unpaired: 'This browser isn’t paired yet, so nothing can drive it. Pairing takes one command and one code.',- offline: 'Paired, but the daemon isn’t answering. Start browsentic-mcp and this reconnects on its own.',+ offline: 'Paired, but the daemon isn’t answering. Start browsentic and this reconnects on its own.',agent: 'The chosen agent can’t run on this machine. Pick another one, or let Browsentic fix it.',};diff --git a/components/run-timeline.tsx b/components/run-timeline.tsxindex ad5f8be..d17cc81 100644--- a/components/run-timeline.tsx+++ b/components/run-timeline.tsx@@ -189,7 +189,7 @@ function ToolRow({size="sm"variant="ghost"onClick={() => onDecide(item.id, true, true)}- title={`Stop asking for ${name} on ${item.site}. Undo with “browsentic-mcp approvals clear”.`}+ title={`Stop asking for ${name} on ${item.site}. Undo with “browsentic approvals clear”.`}>Always on {item.site}</Button>diff --git a/docs/README.md b/docs/README.mdindex a89cf39..380b6dd 100644--- a/docs/README.md+++ b/docs/README.md@@ -51,7 +51,7 @@ How the pieces actually work, for contributors and for anyone integrating.| | || --- | --- || [Tools](reference/tools.md) | All 41 MCP tools with their parameters, plus the resources |-| [CLI](reference/cli.md) | Every `browsentic-mcp` command |+| [CLI](reference/cli.md) | Every `browsentic` command || [Errors](reference/errors.md) | Every error code, what caused it, what to do |---diff --git a/docs/guide/README.md b/docs/guide/README.mdindex d59d416..fadceb5 100644--- a/docs/guide/README.md+++ b/docs/guide/README.md@@ -8,7 +8,7 @@ Three short steps, about five minutes in total. There is no account, no API keyservice.1. **[Install](install.md)** — clone, build, load the extension-2. **[Pair](pair.md)** — put `browsentic-mcp` on your `PATH` and connect your browser to it+2. **[Pair](pair.md)** — put `browsentic` on your `PATH` and connect your browser to it3. **[First run](first-run.md)** — a tour of the side panel, and your first instruction## Using itdiff --git a/docs/guide/agents.md b/docs/guide/agents.mdindex 10e053a..0be1876 100644--- a/docs/guide/agents.md+++ b/docs/guide/agents.md@@ -17,9 +17,9 @@ rather than after.The same thing from a terminal:```sh-browsentic-mcp agent # what is installed, and what runs the side panel-browsentic-mcp agent codex # switch-browsentic-mcp agent setup antigravity+browsentic agent # what is installed, and what runs the side panel+browsentic agent codex # switch+browsentic agent fix antigravity```Switching takes effect on the next instruction. It also drops the conversation being held open:@@ -52,7 +52,7 @@ uncontained.Headless `agy` soft-denies any MCP tool it has no rule for, which would refuse every browser action.The popup shows this as *needs setup*.-Pressing the button — or `browsentic-mcp agent setup antigravity` — appends exactly one entry,+Pressing the button — or `browsentic agent fix antigravity` — appends exactly one entry,`mcp(browsentic/*)`, to `permissions.allow` in `~/.gemini/antigravity-cli/settings.json`, leavingthe rest of that file alone. Nothing is written until you press it. If you have a `deny` rulecovering the same tools, Browsentic will not overrule it — remove it yourself.@@ -93,10 +93,10 @@ 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_NEEDS_PERMISSION` | Antigravity has no rule for Browsentic's tools. Press the button, or `browsentic-mcp agent setup antigravity`. |+| `AGENT_NEEDS_PERMISSION` | Antigravity has no rule for Browsentic's tools. Press the button, or `browsentic agent fix antigravity`. || Codex: "not logged in" | The daemon inherits no session. Run `codex login`, then retry. || "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-mcp agent` reports *needs setup* again. |+| Antigravity answers but never touches the page | Its permission rule was removed. `browsentic agent` reports *needs setup* again. |---diff --git a/docs/guide/approvals.md b/docs/guide/approvals.mdindex 9206d5e..2a6ac8a 100644--- a/docs/guide/approvals.md+++ b/docs/guide/approvals.md@@ -26,9 +26,9 @@ those are the ones you are not meant to be able to click past. The button is hidno single site to attach a grant to.```sh-browsentic-mcp approvals # what no longer asks-browsentic-mcp approvals clear # forget all of them-browsentic-mcp approvals clear a.com # forget one site's+browsentic approvals # what no longer asks+browsentic approvals clear # forget all of them+browsentic approvals clear a.com # forget one site's```---diff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex b5990a2..3f2b24a 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -87,6 +87,7 @@ 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` || `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 |## Site mappingdiff --git a/docs/guide/features/instant-commands.md b/docs/guide/features/instant-commands.mdindex 18576bd..7467a40 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-mcp logs`.** They never reach the daemon. That is+**Local commands leave no trace in `browsentic logs`.** They never reach the daemon. That isexpected, not a bug — the ⚡ is where they show up.**Explaining any single routing decision:**diff --git a/docs/guide/features/recordings.md b/docs/guide/features/recordings.mdindex 8f44148..0c9a7f8 100644--- a/docs/guide/features/recordings.md+++ b/docs/guide/features/recordings.md@@ -62,7 +62,7 @@ between, because replaying the wrong workflow spends real clicks on your real ac## Where they live-In the extension's own storage, not on disk. That is why `browsentic-mcp skills` does not list them,+In the extension's own storage, not on disk. That is why `browsentic skills` does not list them,and why `page_listRecordings` and `page_readRecording` exist as tools.Removing the extension removes them.diff --git a/docs/guide/features/site-maps.md b/docs/guide/features/site-maps.mdindex 2abf608..b847583 100644--- a/docs/guide/features/site-maps.md+++ b/docs/guide/features/site-maps.md@@ -101,7 +101,7 @@ Notes live outside the repository, are re-read on every run so an edit applies task, and hand-written ones take precedence over generated ones.```sh-browsentic-mcp skills # everything currently in scope, and where it came from+browsentic skills # everything currently in scope, and where it came from```---diff --git a/docs/guide/features/skills.md b/docs/guide/features/skills.mdindex 191c8ff..4995e9c 100644--- a/docs/guide/features/skills.md+++ b/docs/guide/features/skills.md@@ -80,7 +80,7 @@ bundled one:no restart.```sh-browsentic-mcp skills # everything the router can see, tagged with where it came from+browsentic skills # everything the router can see, tagged with where it came from```---diff --git a/docs/guide/first-run.md b/docs/guide/first-run.mdindex 4311b47..a13f1c9 100644--- a/docs/guide/first-run.md+++ b/docs/guide/first-run.md@@ -61,9 +61,9 @@ effect. [Approvals](approvals.md) covers the whole gate.Check in this order:-1. `browsentic-mcp status` — is the extension `connected`?-2. `browsentic-mcp agent` — is the agent CLI installed and ready?-3. `browsentic-mcp logs` — run starts, routed skills, every tool call+1. `browsentic status` — is the extension `connected`?+2. `browsentic agent` — is the agent CLI installed and ready?+3. `browsentic logs` — run starts, routed skills, every tool call[Troubleshooting](troubleshooting.md) maps symptoms to fixes.diff --git a/docs/guide/install.md b/docs/guide/install.mdindex 882145a..f51e220 100644--- a/docs/guide/install.md+++ b/docs/guide/install.md@@ -1,7 +1,7 @@# Install-Browsentic is two halves — a browser extension and a local daemon. This page builds both and loads-the extension. Then [pair them](pair.md).+Browsentic is two halves: a browser extension and a local daemon. One command installs both. Then+[pair them](pair.md).There is no account, no API key and no cloud service. Browsentic drives your real browser using theAI agent you already run locally.@@ -13,25 +13,70 @@ AI agent you already run locally.| | Requirement | Check || --- | --- | --- || **Node** | 20 or newer | `node --version` |-| **Browser** | Chrome, or another Chromium browser (Edge, Brave, Arc). Firefox has a build target. | — |+| **Browser** | Chrome, or another Chromium browser (Edge, Brave, Arc) | — || **Agent** | One of [Claude Code](https://claude.com/claude-code), [Codex](https://developers.openai.com/codex/cli) or [Antigravity](https://antigravity.google/docs/cli/install) on your `PATH`, logged in | `claude --version`, `codex --version`, `agy --version` |-| **git** | To clone the repository | `git --version` |-Four things worth knowing before you start:+Two things worth knowing before you start:- **An agent CLI is only needed for the side panel.** It is what the daemon spawns to reason aboutan instruction. If you only ever drive the browser from an MCP client, the daemon spawns nothingand no agent CLI is required. See [Choosing an agent](agents.md).- **Only one of the three is needed.** Browsentic checks all three and tells you in the popup whichare installed. Switching is a click.-- **Yarn is not a prerequisite.** The pinned Yarn 4 release ships inside the repository and the- setup script invokes it through Node. No global install, no Corepack.-- **`@browsentic/mcp` is not published to npm.** Install from source; `npx -y @browsentic/mcp`- will not resolve.----## 1. Clone and build+## Install++```sh+npx browsentic 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.++Two steps are left. Both happen inside the browser, so only you can do them.++**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.++Pin Browsentic to the toolbar so the popup is one click away.++**2. Paste the pairing code** into the popup and press Connect. It is single use and lives for ten+minutes. `browsentic pair` issues another.++To install the command permanently rather than through `npx`:++```sh+npm i -g browsentic+```++### Updating++```sh+npx browsentic@latest update+```++That 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. See [Maintenance](maintenance.md).++### Firefox++Not yet. Release Firefox refuses unsigned extensions, and an add-on loaded through+`about:debugging` is discarded when the browser restarts, so there is nothing durable to install. A+signed build distributed through addons.mozilla.org is the fix and it is not ready.++Developer Edition and Nightly can load `dist/firefox-mv2` from a source checkout with+`xpinstall.signatures.required` set to `false`.++---++## From source++Use this if you are working on Browsentic itself, or want to run an unreleased commit.```shgit clone https://github.com/imshaikot/browsentic.git@@ -41,7 +86,8 @@ node scripts/setup.mjsThat runs four steps: extension dependencies, extension build, daemon dependencies, daemon build.`mcp/` is a separate Yarn project with its own lockfile, which is why the root install does not-cover it. Once dependencies exist, `yarn setup` re-runs the same thing.+cover it. Yarn itself is not a prerequisite: the pinned Yarn 4 release ships inside the repository+and the setup script invokes it through Node.When it finishes you have:@@ -50,21 +96,9 @@ dist/chrome-mv3 the unpacked extensionmcp/dist the daemon and MCP server```-## 2. Load the extension--1. Open `chrome://extensions`-2. Turn on **Developer mode** (top right)-3. **Load unpacked** → select `dist/chrome-mv3`--Pin Browsentic to the toolbar so the popup is one click away.--**Firefox:** `yarn build:firefox`, then load `dist/firefox-mv2` through `about:debugging` →-**This Firefox** → **Load Temporary Add-on**. Firefox is a supported build target, but Chromium is-what Browsentic is developed against.--Installing from source means Chrome will not auto-update the extension, and will not auto-reload it-after a rebuild — press ↻ on the Browsentic card at `chrome://extensions` yourself. See-[Maintenance](maintenance.md).+Load `dist/chrome-mv3` directly through **Load unpacked**, or put the CLI on your `PATH` with+`yarn mcp: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.---diff --git a/docs/guide/maintenance.md b/docs/guide/maintenance.mdindex e25ff51..2d3c559 100644--- a/docs/guide/maintenance.md+++ b/docs/guide/maintenance.md@@ -13,14 +13,14 @@ Then reload the extension at `chrome://extensions` (↻ on the Browsentic card)daemon:```sh-browsentic-mcp restart+browsentic restart```Both steps are needed, for the same reason in two places: **nothing reloads itself.** Chrome doesnot auto-reload an unpacked extension, and a running daemon keeps the old build in memory until itis replaced.-**Rebuild both halves together.** If only one side is rebuilt, `browsentic-mcp status` reports+**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 tellsyour MCP clients the list changed — it degrades loudly rather than into tool calls that fail at thefar end — but you should fix the drift rather than run on it.@@ -30,7 +30,7 @@ Your pairing survives updates. `yarn mcp:link` only needs re-running if the link### Why `yarn mcp:build` alone changes nothingThe daemon has no start command: the first CLI or MCP client that needs it spawns it, and it lives-until `browsentic-mcp stop` or 30 idle minutes with nothing attached. A rebuild does not touch the+until `browsentic stop` or 30 idle minutes with nothing attached. A rebuild does not touch theprocess already running.`yarn mcp:restart` is the one that does both — it rebuilds, stops the stale daemon, and brings up@@ -41,9 +41,9 @@ the fresh build.## Uninstalling```sh-browsentic-mcp revoke # unpair every browser-browsentic-mcp stop # stop the daemon-yarn mcp:unlink # remove browsentic-mcp from PATH+browsentic revoke # unpair every browser+browsentic stop # stop the daemon+yarn mcp:unlink # remove browsentic from PATHrm -rf ~/.browsentic ~/browsentic```diff --git a/docs/guide/mcp-clients.md b/docs/guide/mcp-clients.mdindex efe08aa..48b23b3 100644--- a/docs/guide/mcp-clients.md+++ b/docs/guide/mcp-clients.md@@ -14,14 +14,15 @@ This direction is fully agent-agnostic. Nothing here depends on which CLI you pi**Claude Code:**```sh-claude mcp add browsentic -- browsentic-mcp+claude mcp add browsentic -- browsentic mcp```**Codex CLI** — TOML, in `~/.codex/config.toml`:```toml[mcp_servers.browsentic]-command = "browsentic-mcp"+command = "browsentic"+args = ["mcp"]```**Anything else** — most clients take a JSON block of this shape:@@ -29,13 +30,13 @@ command = "browsentic-mcp"```json{"mcpServers": {- "browsentic": { "command": "browsentic-mcp" }+ "browsentic": { "command": "browsentic", "args": ["mcp"] }}}```Check your client's own documentation for the exact file and key. The *command* is the part that-matters, and it is `browsentic-mcp` with no arguments everywhere.+matters, and it is `browsentic` with the single argument `mcp` everywhere.**MCP servers are loaded at session start**, so restart the client session after registering.Tools missing from a session you registered mid-flight is the single most common surprise here.@@ -76,7 +77,7 @@ changes is everything around the tool call.| Skills and site notes | Routed and applied automatically | Not applied || Recordings, site mapping | Full access | Readable only (`page_listRecordings`, `page_readRecording`) || Voice input | Yes | No |-| Appears in `browsentic-mcp logs` | Yes | Yes |+| Appears in `browsentic logs` | Yes | Yes |### Consequential actions are denied, not waiveddiff --git a/docs/guide/pair.md b/docs/guide/pair.mdindex cf0c42f..9170786 100644--- a/docs/guide/pair.md+++ b/docs/guide/pair.md@@ -6,29 +6,21 @@ Assumes you have [installed and loaded the extension](install.md).----## 1. Put the CLI on your PATH+`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.-```sh-yarn mcp:link-```--This runs `npm link` inside `mcp/`, which writes `browsentic-mcp` and `browsentic-mcpd` to your-global npm prefix. It reaches outside the repository, which is why it is a separate step from the-build.+----Confirm:+## 1. Redeem a pairing code```sh-browsentic-mcp --version+browsentic pair```-If the command is not found, your global npm prefix is not on `PATH`. Find it with `npm prefix -g`-and add its `bin` directory.--## 2. Redeem a pairing code+Through `npx`, if you have not installed the command globally:```sh-browsentic-mcp pair+npx browsentic pair```This starts the daemon if it is not already running and prints a code:@@ -45,25 +37,27 @@ Open the Browsentic popup, paste the code, press **Connect**.The daemon issues a long-lived session key that survives browser and daemon restarts, and dies onlywhen you revoke it. You do not need to pair again after an update.-## 3. Verify+## 2. Verify```sh-browsentic-mcp status+browsentic status``````-daemon: running on 127.0.0.1:8765 (pid 41207, v0.2.1)-extension: connected (v0.2.1)+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 syncpaired: 1```-All four lines matter:+Every line matters:| Line | What it means || --- | --- || `daemon` | The local process is up, on one of ports 8765–8767 |-| `extension` | Your browser is connected right now. `offline` means the browser is closed or unpaired |+| `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 |@@ -89,9 +83,9 @@ for the mechanism, [internals/transport.md](../internals/transport.md).## Managing pairings```sh-browsentic-mcp sessions # which browsers are paired-browsentic-mcp revoke # unpair every browser-browsentic-mcp revoke <origin> # unpair one+browsentic sessions # which browsers are paired+browsentic revoke # unpair every browser+browsentic revoke <origin> # unpair one```Several browsers can be *paired*, but the daemon keeps **one live link** at a time — a newerdiff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex 871819c..db95c3b 100644--- a/docs/guide/troubleshooting.md+++ b/docs/guide/troubleshooting.md@@ -7,9 +7,9 @@ Symptom, cause, fix. For what an error *code* means, see [reference/errors.md](.## Start here```sh-browsentic-mcp status # daemon, extension, manifest sync, pairings-browsentic-mcp agent # which agents are installed, which one runs the side panel-browsentic-mcp logs # run starts, routed skills, every tool call and its outcome+browsentic status # daemon, extension, manifest sync, pairings+browsentic agent # which agents are installed, which one runs the side panel+browsentic 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`.@@ -21,10 +21,13 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| Symptom | Cause | Fix || --- | --- | --- || 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-mcp pair` for a fresh one. A failed attempt does not burn the outstanding code |-| "No Browsentic daemon is running" | Nothing on 8765–8767 | `browsentic-mcp status`; check `browsentic-mcp logs` |-| `browsentic-mcp: command not found` | The global npm prefix is not on `PATH` | `npm prefix -g`, then add its `bin` directory |-| `EXTENSION_OFFLINE` | Browser closed, or not paired | Open the browser; `browsentic-mcp sessions` to check pairing |+| "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` |+| `browsentic: command not found` | The global npm prefix is not on `PATH` | `npm prefix -g`, then add its `bin` directory |+| `EXTENSION_OFFLINE` | Browser closed, or not paired | Open the browser; `browsentic sessions` to check pairing |+| "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` |+| 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 |+| 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 |## MCP clients@@ -39,10 +42,10 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d| Symptom | Cause | Fix || --- | --- | --- |-| `AGENT_MISSING` | The chosen CLI is not on the *daemon's* `PATH` | `browsentic-mcp agent` to see all three; set `agents.<name>.bin` to an absolute path in `config.json` |-| `AGENT_NEEDS_PERMISSION` | Antigravity has no rule allowing Browsentic's MCP tools | Press the button in the popup, or `browsentic-mcp agent setup antigravity` |+| `AGENT_MISSING` | The chosen CLI is not on the *daemon's* `PATH` | `browsentic agent` to see all three; set `agents.<name>.bin` to an absolute path in `config.json` |+| `AGENT_NEEDS_PERMISSION` | Antigravity has no rule allowing Browsentic's MCP tools | Press the button in the popup, or `browsentic agent fix antigravity` || "does not understand the flags Browsentic uses" | The agent CLI is too old | Update it |-| Antigravity answers but never touches the page | Its permission rule was removed | `browsentic-mcp agent` — it reports *needs setup* again |+| Antigravity answers but never touches the page | Its permission rule was removed | `browsentic agent` — it reports *needs setup* again || Codex fails with "not logged in" | The daemon inherits no session | `codex login`, then retry |## Pages and tabs@@ -72,17 +75,17 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d## Useful commands```sh-browsentic-mcp status # daemon, extension and agent state-browsentic-mcp agent # which agents are installed, and which one runs the side panel-browsentic-mcp sessions # which browsers are paired-browsentic-mcp revoke # unpair everything, or one origin-browsentic-mcp skills # every skill in scope, and where it came from-browsentic-mcp approvals # the "always on this site" grants-browsentic-mcp tools # the tool manifest, no browser needed-browsentic-mcp logs # run starts, routed skills, every tool call-browsentic-mcp token # the control token, for MCP clients-browsentic-mcp restart # swap the running daemon for a fresh one-browsentic-mcp stop+browsentic status # daemon, extension and agent state+browsentic agent # which agents are installed, and which one runs the side panel+browsentic sessions # which browsers are paired+browsentic revoke # unpair everything, or one origin+browsentic skills # every skill in scope, and where it came from+browsentic approvals # the "always on this site" grants+browsentic tools # the tool manifest, no browser needed+browsentic logs # run starts, routed skills, every tool call+browsentic token # the control token, for MCP clients+browsentic restart # swap the running daemon for a fresh one+browsentic stop```Full descriptions in [reference/cli.md](../reference/cli.md).diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.mdindex 1588e09..bf68373 100644--- a/docs/internals/agent-runs.md+++ b/docs/internals/agent-runs.md@@ -27,7 +27,7 @@ A matched rule flagged `risky` — the label contains *buy*, *pay*, *delete*, *sA confident match runs straight through `invokeForHarness` in the background and emits a`source: 'local'` timeline entry with a bolt. It never reaches the daemon, so it leaves no trace in-`browsentic-mcp logs`. If a local command runs and *fails*, it escalates rather than reporting the+`browsentic logs`. If a local command runs and *fails*, it escalates rather than reporting thefailure.The bias is deliberate: escalating something the browser could have handled costs a round trip;@@ -45,7 +45,7 @@ sequenceDiagramparticipant B as Background SWparticipant D as Daemonparticipant K as claude -p- participant M as browsentic-mcp (child)+ participant M as browsentic mcp (child)S->>B: instruction + the tab it was typed onB->>B: resolve tab → session, tryFastPath() — grammar@@ -64,7 +64,7 @@ sequenceDiagram```**The loop closes on itself.** The daemon spawns the agent CLI, which spawns *another*-`browsentic-mcp`, which connects back to the same daemon. That indirection is what lets an agent run+`browsentic mcp`, which connects back to the same daemon. That indirection is what lets an agent runreuse the exact tool surface an external client gets, while still being gated differently.`BROWSENTIC_AGENT_RUN` is the whole mechanism. The child MCP server reads it, stamps `runId` on everydiff --git a/docs/internals/contributing.md b/docs/internals/contributing.mdindex 5bb5fd7..a4e475a 100644--- a/docs/internals/contributing.md+++ b/docs/internals/contributing.md@@ -49,7 +49,7 @@ yarn check # both type checks plus both fixture suites### The daemon keeps the old build in memoryThe daemon has no start command: the first CLI or MCP client that needs it spawns it, and it lives-until `browsentic-mcp stop` or 30 idle minutes with nothing attached.+until `browsentic stop` or 30 idle minutes with nothing attached.The flip side is that **a rebuild alone changes nothing while a daemon is running**. That is what`yarn mcp:restart` is for: it rebuilds, stops the stale daemon and brings up the fresh build. Thediff --git a/docs/internals/overview.md b/docs/internals/overview.mdindex cf906f7..962ad64 100644--- a/docs/internals/overview.md+++ b/docs/internals/overview.md@@ -20,7 +20,7 @@ You ──speak or type──> Extension ──local WebSocket──> Daemon ─▲ (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 daemon ──> the same browser```Everything binds to `127.0.0.1`. Nothing listens on a public interface, and there is no cloud@@ -34,7 +34,7 @@ component.| --- | --- | --- | --- || **Extension** | The browser | As long as the browser runs | Owns the tabs. Runs the side panel, the popup, the background service worker and one content script per page || **Daemon** (`daemon-main.js`) | Auto-spawned by the first CLI or MCP client that needs it | Until 30 minutes idle with no extension and no control clients | Owns the browser link, authorization, agent runs, screenshot writes, skill and site-map storage |-| **MCP server** (`browsentic-mcp`) | The MCP client, over stdio | The client's session | Translates MCP tool calls into daemon control frames. One process per client |+| **MCP server** (`browsentic mcp`) | The MCP client, over stdio | The client's session | Translates MCP tool calls into daemon control frames. One process per client || **Agent** (`claude -p` and friends) | The daemon, per side-panel instruction | One instruction | Reasons about the instruction and calls page tools. Contained to Browsentic's own MCP server |The MCP server is deliberately thin: it holds **no browser state**. Kill it and the browser link is@@ -56,7 +56,7 @@ Everything in this section is one of two request shapes:| **[Path B](agent-runs.md)** | You type into the side panel. Goes through the intent funnel, then possibly spawns an agent CLI which loops back through Path A |Path B closing back onto Path A is the central trick: the agent the daemon spawns runs *another*-`browsentic-mcp`, which connects back to the same daemon. That is what lets an agent run reuse the+`browsentic mcp`, which connects back to the same daemon. That is what lets an agent run reuse theexact tool surface an external client gets while still being [gated differently](guardrails.md).---diff --git a/docs/internals/registry.md b/docs/internals/registry.mdindex 373b620..34ff67e 100644--- a/docs/internals/registry.md+++ b/docs/internals/registry.md@@ -45,7 +45,7 @@ underscores** — `page.get_info` would come back as `page.get.info`.The extension hashes its bundled manifest and sends the hash in `hello`. If it differs from thedaemon's, the daemon:-1. flags `manifestInSync: false` — visible in `browsentic-mcp status` and `browsentic_status`;+1. flags `manifestInSync: false` — visible in `browsentic status` and `browsentic_status`;2. asks the extension for its actual descriptor list over a `describe` frame and **adopts it** — thebrowser is the authority on what the browser can do;3. broadcasts `manifest-changed` to control clients, which makes each MCP server emitdiff --git a/docs/internals/request-path.md b/docs/internals/request-path.mdindex 62b8549..5d52417 100644--- a/docs/internals/request-path.md+++ b/docs/internals/request-path.md@@ -11,7 +11,7 @@ The unconditional path. No agent on Browsentic's side, no intent funnel.```mermaidsequenceDiagramparticipant C as MCP client- participant M as browsentic-mcp+ participant M as browsentic mcpparticipant D as Daemonparticipant B as Background SWparticipant P as Content script@@ -33,10 +33,10 @@ sequenceDiagram## Details worth knowing-**`browsentic-mcp` starts the daemon if needed.** `ensureDaemon()` reads the lockfile, checks the+**`browsentic mcp` starts the daemon if needed.** `ensureDaemon()` reads the lockfile, checks thepid is alive and `/health` answers, and otherwise spawns a detached `daemon-main.js`, polling for upto 8 seconds. It never compares versions, so a running daemon keeps serving an old build until-`browsentic-mcp restart`.+`browsentic restart`.**External calls are visible.** The daemon emits a `tool`/`toolResult` pair tagged`source: 'external'` on the run channel, so anything an MCP client does appears on the user'sdiff --git a/docs/internals/state.md b/docs/internals/state.mdindex 1664dcc..44a3a7f 100644--- a/docs/internals/state.md+++ b/docs/internals/state.md@@ -14,6 +14,7 @@ Nothing lives in the repository.└── skills/ hand-written skill overrides~/browsentic/ (paths configurable)+├── extension/chrome-mv3/ the unpacked extension `browsentic setup` installs├── skills/ panel uploads + activated site maps│ ├── acme-com/SKILL.md│ └── .staging/ maps awaiting review — unreadable to the loader@@ -22,11 +23,11 @@ Nothing lives in the repository.| File | Written by | Notes || --- | --- | --- |-| `daemon.json` | Each daemon at startup | The control token dies with the daemon that minted it. Read it with `browsentic-mcp token` |-| `auth.json` | Pairing | Session keys are per extension origin and survive restarts. Cleared by `browsentic-mcp revoke` |+| `daemon.json` | Each daemon at startup | The control token dies with the daemon that minted it. Read it with `browsentic token` |+| `auth.json` | Pairing | Session keys are per extension origin and survive restarts. Cleared by `browsentic revoke` || `config.json` | You, and the agent picker | Re-read before every run — no restart needed. [Reference](../guide/configuration.md) || `approvals.json` | **Always on ‹host›** | One action + host per entry. Only short-circuits a `confirm` |-| `daemon.log` | The daemon | `browsentic-mcp logs`. Local [instant commands](../guide/features/instant-commands.md) never appear here, by design |+| `daemon.log` | The daemon | `browsentic logs`. Local [instant commands](../guide/features/instant-commands.md) never appear here, by design |## The three exceptions@@ -41,8 +42,9 @@ when the browser closes.## Relocating-`BROWSENTIC_HOME` moves `~/.browsentic` wholesale. `screenshotDir` and `skillsDir` in config move the-two `~/browsentic` subdirectories independently.+`BROWSENTIC_HOME` moves `~/.browsentic` wholesale. `screenshotDir` and `skillsDir` in config move+those two `~/browsentic` subdirectories independently, and `browsentic setup --dir` installs the+extension somewhere else.---diff --git a/docs/internals/subsystems.md b/docs/internals/subsystems.mdindex e259d88..cdb1794 100644--- a/docs/internals/subsystems.md+++ b/docs/internals/subsystems.md@@ -53,7 +53,7 @@ On stop, a one-shot [`task`-mode](guardrails.md#two-spawn-modes) agent call turnordered, named steps. That call cannot reach the browser — `{"mcpServers":{}}` is asserted in itsargv.-Recordings live in **extension storage, not on disk**, which is why `browsentic-mcp skills` does not+Recordings live in **extension storage, not on disk**, which is why `browsentic skills` does notlist them and why `page_listRecordings` / `page_readRecording` exist as tools.---diff --git a/docs/internals/transport.md b/docs/internals/transport.mdindex 7bf650f..fab6af2 100644--- a/docs/internals/transport.md+++ b/docs/internals/transport.md@@ -49,7 +49,7 @@ leaked once does not open every future daemon.Clients re-read the lockfile before every connection, and `probeExisting()` matches the pid in`/health` against the lockfile so it never offers a token to a daemon that never issued it.-Read it with `browsentic-mcp token`.+Read it with `browsentic token`.---@@ -57,7 +57,7 @@ Read it with `browsentic-mcp token`.The extension connects to nothing until you pair it.-1. `browsentic-mcp pair` asks the daemon for a code: 8 characters from an alphabet with the+1. `browsentic pair` asks the daemon for a code: 8 characters from an alphabet with theambiguous glyphs removed, valid **10 minutes**, single use.2. You paste it into the popup. The extension dials `ws://127.0.0.1:<port>/extension`, walking thethree ports, and sends `hello` — which names *which* secret it holds and a fresh nonce, never the@@ -73,7 +73,7 @@ The extension connects to nothing until you pair it.6. On pairing, the daemon mints a **session key** (32 random bytes) bound to that extension originand returns it 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- you `browsentic-mcp revoke`.+ you `browsentic revoke`.### Why the mutual half mattersdiff --git a/docs/reference/README.md b/docs/reference/README.mdindex 9372ca5..d802e9d 100644--- a/docs/reference/README.md+++ b/docs/reference/README.md@@ -6,7 +6,7 @@ Lookup tables. Nothing here explains a workflow — see the [user guide](../guid| | || --- | --- || [Tools](tools.md) | All 41 MCP tools with their parameters, the three read-only resources, and the reserved actions that never become tools |-| [CLI](cli.md) | Every `browsentic-mcp` command |+| [CLI](cli.md) | Every `browsentic` command || [Errors](errors.md) | Every error code, where it comes from, and what to do about it |The tool list is generated from [`lib/actions/registry.ts`](../../lib/actions/registry.ts). Thediff --git a/docs/reference/cli.md b/docs/reference/cli.mdindex 27c3e28..a353e15 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -1,23 +1,45 @@# CLI reference```-browsentic-mcp <command>+browsentic <command>```-With no command it serves MCP over stdio — that is what an [MCP client](../guide/mcp-clients.md)-runs, and it is not something you type yourself.--Every command starts the daemon if one is not already running.+With no command it prints usage. Most commands start the daemon if one is not already running;+`status`, `stop`, `logs`, `token`, `tools`, `skills` and `approvals` do not.---+## Installing++| Command | Does |+| --- | --- |+| `browsentic setup` | Install the extension, start the daemon, print a pairing code |+| `browsentic update` | Refresh the installed extension in place and restart the daemon |++`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.++The install path never carries a version, deliberately. Chrome derives an unpacked extension's ID+from the absolute path of its directory, and the daemon binds each session key to the resulting+origin, so a versioned path would unpair the browser on every update.++| 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` only for now. See [install](../guide/install.md) for the Firefox situation |+| `--json` | Machine-readable result |++See [guide/install.md](../guide/install.md).+## Pairing| Command | Does || --- | --- |-| `browsentic-mcp pair` | Issue a one-time code to type into the extension popup. 8 characters, valid 10 minutes, single use |-| `browsentic-mcp sessions` | List paired browsers |-| `browsentic-mcp revoke [origin]` | Unpair one browser, or all of them |+| `browsentic pair` | Issue a one-time code to type into the extension popup. 8 characters, valid 10 minutes, single use |+| `browsentic sessions` | List paired browsers |+| `browsentic revoke [origin]` | Unpair one browser, or all of them |See [guide/pair.md](../guide/pair.md).@@ -25,33 +47,45 @@ See [guide/pair.md](../guide/pair.md).| Command | Does || --- | --- |-| `browsentic-mcp agent` | Show which agent runs the side panel, and which are installed |-| `browsentic-mcp agent <name>` | Switch to `claude`, `codex` or `antigravity` |-| `browsentic-mcp agent setup <name>` | Let Browsentic fix what that agent still needs |+| `browsentic agent` | Show which agent runs the side panel, and which are installed |+| `browsentic agent <name>` | Switch to `claude`, `codex` or `antigravity` |+| `browsentic agent fix <name>` | Let Browsentic fix what that agent still needs |-`agent setup antigravity` appends exactly one entry, `mcp(browsentic/*)`, to `permissions.allow` in+`agent fix antigravity` appends exactly one entry, `mcp(browsentic/*)`, to `permissions.allow` in`~/.gemini/antigravity-cli/settings.json`. See [guide/agents.md](../guide/agents.md).+The verb was `agent setup` before `setup` came to mean installing the extension. The old spelling+still works and is undocumented.++## MCP++| Command | Does |+| --- | --- |+| `browsentic mcp` | Serve MCP over stdio. What an [MCP client](../guide/mcp-clients.md) runs, not something you type |++`browsentic-mcp` is a legacy alias binary that serves MCP on bare invocation, so client+configurations written against the older name keep working.+## State and diagnostics| Command | Does || --- | --- |-| `browsentic-mcp status` | Daemon and extension connection state, manifest sync, pairing count |-| `browsentic-mcp logs` | Print the daemon log (`~/.browsentic/daemon.log`) |-| `browsentic-mcp tools` | Print the bundled tool manifest as JSON. **No browser needed** |-| `browsentic-mcp skills` | Every skill the router can see, tagged `bundled`, `user` or `uploaded` |-| `browsentic-mcp approvals` | The "always on this site" grants |-| `browsentic-mcp approvals clear [host]` | Forget them — all, or one site's |-| `browsentic-mcp token` | The control token, for MCP clients. Not for the browser |+| `browsentic status` | Daemon and extension state, the installed build, manifest sync, pairing count |+| `browsentic logs` | Print the daemon 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 |+| `browsentic approvals clear [host]` | Forget them, all or one site's |+| `browsentic token` | The control token, for MCP clients. Not for the browser |## Lifecycle| Command | Does || --- | --- |-| `browsentic-mcp stop` | Stop the background daemon |-| `browsentic-mcp restart` | Stop the daemon and bring up a fresh one |-| `browsentic-mcp --version` / `-v` | Print the version |-| `browsentic-mcp help` / `--help` / `-h` | Usage |+| `browsentic stop` | Stop the background daemon |+| `browsentic restart` | Stop the daemon and bring up a fresh one |+| `browsentic --version` / `-v` | Print the version |+| `browsentic help` / `--help` / `-h` | Usage |**A rebuild does not replace a running daemon.** It keeps the old code in memory until `stop` or`restart`. In the repository, `yarn mcp:restart` chains the rebuild with the restart.@@ -65,7 +99,7 @@ Not the CLI, but frequently wanted alongside it:| Command | Does || --- | --- || `yarn setup` | Install and build both halves |-| `yarn mcp:link` | Put `browsentic-mcp` on your `PATH` |+| `yarn mcp:link` | Put `browsentic` on your `PATH` from a source checkout || `yarn mcp:unlink` | Take it off again || `yarn mcp:restart` | Rebuild the daemon, then swap the running one for it || `yarn mcp:manifest` | Build and print the tool manifest |diff --git a/docs/reference/errors.md b/docs/reference/errors.mdindex 546b54c..04a7b2e 100644--- a/docs/reference/errors.md+++ b/docs/reference/errors.md@@ -54,7 +54,7 @@ repeatedly: failures carry the *fix* in the message, and a failed tool call neve| Code | Origin | Meaning and next move || --- | --- | --- || `AGENT_MISSING` | Runner | The chosen agent's binary is not on the *daemon's* `PATH`. Set `agents.<name>.bin` to an absolute path |-| `AGENT_NEEDS_PERMISSION` | Runner | Antigravity has no rule allowing Browsentic's MCP tools. `browsentic-mcp agent setup antigravity` |+| `AGENT_NEEDS_PERMISSION` | Runner | Antigravity has no rule allowing Browsentic's MCP tools. `browsentic agent fix antigravity` || `AGENT_UNUSABLE` | Runner | The CLI is present but cannot run — usually too old for the flags Browsentic passes |## Guardrailsdiff --git a/docs/reference/tools.md b/docs/reference/tools.mdindex a8bf206..4c6d67d 100644--- a/docs/reference/tools.md+++ b/docs/reference/tools.md@@ -808,7 +808,7 @@ change an action, regenerate and update this page to match.At runtime, drift cannot hide: the extension sends a hash of its manifest when it connects, thedaemon compares it against its own, logs `DRIFTED` if they differ, adopts the browser's listing as-the truth, and notifies connected MCP clients that the tool list changed. `browsentic-mcp status`+the truth, and notifies connected MCP clients that the tool list changed. `browsentic status`reports whether the two halves are in sync.---diff --git a/entrypoints/popup/App.tsx b/entrypoints/popup/App.tsxindex 2882aee..f745fab 100644--- a/entrypoints/popup/App.tsx+++ b/entrypoints/popup/App.tsx@@ -15,7 +15,7 @@ import { cn } from '@/lib/utils';const BLOCKED: Record<StatusBlocker, string> = {unpaired: 'Pair this browser to start',- offline: 'The daemon isn’t answering — start browsentic-mcp',+ offline: 'The daemon isn’t answering — start browsentic',agent: 'That agent cannot run — pick another below',};diff --git a/lib/bridge/socket.ts b/lib/bridge/socket.tsindex 6e32008..4dca179 100644--- a/lib/bridge/socket.ts+++ b/lib/bridge/socket.ts@@ -331,7 +331,7 @@ export async function connectDaemon(): Promise<void> {export async function pairDaemon(pairingToken: string): Promise<{ ok: boolean; error?: string }> {const code = pairingToken.replace(/[\s-]/g, '').toUpperCase();- if (!code) return { ok: false, error: 'Enter the pairing code from "browsentic-mcp pair".' };+ if (!code) return { ok: false, error: 'Enter the pairing code from "browsentic pair".' };disconnectSocket();clearTimeout(reconnectTimer);@@ -340,7 +340,7 @@ export async function pairDaemon(pairingToken: string): Promise<{ ok: boolean; epairingResult = resolve;dial({ kind: 'pair', secret: code }, 0);setTimeout(- () => settlePairing({ ok: false, error: 'No Browsentic daemon is running. Start one with "browsentic-mcp pair".' }),+ () => settlePairing({ ok: false, error: 'No Browsentic daemon is running. Start one with "browsentic pair".' }),PAIRING_TIMEOUT_MS,);});diff --git a/mcp/src/agent/config.ts b/mcp/src/agent/config.tsindex 9dce5f2..5f922a5 100644--- a/mcp/src/agent/config.ts+++ b/mcp/src/agent/config.ts@@ -23,6 +23,12 @@ export interface AgentConfig {guardrails?: GuardrailConfig;screenshotDir?: string;skillsDir?: string;+ /**+ * Where `browsentic setup --dir` put the unpacked extension, so `update` writes to the same+ * place. Only set when it is not the default; needed for sandboxed browsers (Flatpak, Snap)+ * that cannot read ~/browsentic.+ */+ extensionDir?: string;siteMap?: {research?: boolean;allowClicks?: boolean;@@ -172,3 +178,14 @@ function write(config: StoredConfig): void {mkdirSync(stateDir, { recursive: true, mode: 0o700 });writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });}++/**+ * Remember where `setup --dir` installed, so a later `update` writes to the same directory+ * instead of silently laying down a second copy at the default path.+ */+export function rememberExtensionDir(dir: string | undefined): void {+ const stored = readStored();+ if (dir) stored.extensionDir = dir;+ else delete stored.extensionDir;+ write(stored);+}diff --git a/mcp/src/cli.ts b/mcp/src/cli.tsindex a455ddf..8ef03be 100644--- a/mcp/src/cli.ts+++ b/mcp/src/cli.ts@@ -7,7 +7,7 @@ import { assertToolNamesRoundTrip, toolNameFor } from '@/lib/actions/tool-names'import { basename, join } from 'node:path';import { agentSkills } from './agent/agent-skills';import { forgetGrants, listGrants } from './agent/approvals';-import { readAgentConfig } from './agent/config';+import { readAgentConfig, rememberExtensionDir } from './agent/config';import { loadSkills, skillDirNames, uploadedSkillsDir } from './agent/skills';import { ensureDaemon, probeExisting } from './ensure-daemon';import { install, InstallError, readStamp } from './install';@@ -195,12 +195,13 @@ async function showStatus(): Promise<void> {// "Updated the CLI, never reloaded the extension" is the failure this reports. Without it// the only symptom is a drifted manifest, which names no cause the user can act on.- const stamp = readStamp(extensionDir());+ const installedIn = extensionDir(readAgentConfig().extensionDir);+ const stamp = readStamp(installedIn);if (stamp) {const stale = status.connected && status.extensionVersion !== stamp.version;console.log(- `installed: v${stamp.version} at ${extensionDir()}` +- (stale ? ' — press ↻ at chrome://extensions to load it' : ''),+ `installed: v${stamp.version} at ${installedIn}` ++ (stale ? ', press ↻ at chrome://extensions to load it' : ''),);}console.log(`extension: ${status.connected ? `connected (v${status.extensionVersion})` : 'not connected'}`);@@ -306,7 +307,11 @@ async function setup(argv: string[]): Promise<void> {process.exit(1);}- const dir = extensionDir(valueOf('dir'));+ // An explicit --dir is remembered, so `update` lands in the same place rather than laying+ // down a second copy at the default path and leaving the browser pointed at the first.+ const chosen = valueOf('dir');+ const dir = extensionDir(chosen ?? readAgentConfig().extensionDir);+ if (chosen) rememberExtensionDir(chosen);const json = flag('json');let result;diff --git a/scripts/release-notes.mjs b/scripts/release-notes.mjsindex 81d0460..16f5168 100644--- a/scripts/release-notes.mjs+++ b/scripts/release-notes.mjs@@ -88,17 +88,29 @@ function renderNotes(version, commits, prevTag) {lines.push('### Install','',- `Download \`browsentic-${version}-chrome.zip\`, unzip it, then load the folder at \`chrome://extensions\``,- 'with **Developer mode** on. Firefox users want the `-firefox.zip`.',+ '```sh',+ `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.','',- 'The daemon runs from source:',+ 'Already running an older version? `npx browsentic@latest update` refreshes the extension in',+ 'place and keeps your browser paired. Press ↻ on the Browsentic card afterwards.',+ '',+ '<details><summary>From the zips, or from source</summary>',+ '',+ `The \`-chrome.zip\` and \`-firefox.zip\` below are the same builds, for loading by hand. Firefox`,+ 'needs Developer Edition or Nightly, since release Firefox refuses unsigned extensions.','','```sh',`git clone --branch v${version} https://github.com/${REPO}.git`,'cd browsentic && yarn setup && yarn mcp:link',- 'browsentic-mcp pair',+ 'browsentic setup','```','',+ '</details>',+ '',prevTag? `**Full changelog**: https://github.com/${REPO}/compare/${prevTag}...v${version}`: `**Full changelog**: https://github.com/${REPO}/commits/v${version}`,diff --git a/scripts/setup.mjs b/scripts/setup.mjsindex 23a7aa0..138eb86 100644--- a/scripts/setup.mjs+++ b/scripts/setup.mjs@@ -53,6 +53,6 @@ console.log(`Two steps are left. Both reach outside this directory, so they stay separate:- yarn mcp:link puts \`browsentic-mcp\` on your PATH (writes to the global npm prefix)- browsentic-mcp pair prints a single use code, valid for 10 minutes+ yarn mcp:link puts \`browsentic\` on your PATH (writes to the global npm prefix)+ browsentic pair prints a single use code, valid for 10 minutes`);