Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs(cli): rewrite the install path around npx, and rename the command

Shahriar51ec719418cb
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 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@v5
with:
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.md
index 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.tsx
index 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 a
terminal 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.tsx
index 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.tsx
index 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.md
index 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.md
index 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 key
service.
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 it
3. **[First run](first-run.md)** — a tour of the side panel, and your first instruction
## Using it
diff --git a/docs/guide/agents.md b/docs/guide/agents.md
index 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`, leaving
the rest of that file alone. Nothing is written until you press it. If you have a `deny` rule
covering 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.md
index 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 hid
no 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.md
index 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 mapping
diff --git a/docs/guide/features/instant-commands.md b/docs/guide/features/instant-commands.md
index 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 is
expected, 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.md
index 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.md
index 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 t
ask, 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.md
index 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.md
index 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.md
index 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 the
AI 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 about
an instruction. If you only ever drive the browser from an MCP client, the daemon spawns nothing
and 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 which
are 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.
```sh
git clone https://github.com/imshaikot/browsentic.git
@@ -41,7 +86,8 @@ node scripts/setup.mjs
That 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 extension
mcp/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.md
index 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 does
not auto-reload an unpacked extension, and a running daemon keeps the old build in memory until it
is 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 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.
@@ -30,7 +30,7 @@ Your pairing survives updates. `yarn mcp:link` only needs re-running if the link
### Why `yarn mcp:build` alone changes nothing
The 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 the
process 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 PATH
rm -rf ~/.browsentic ~/browsentic
```
diff --git a/docs/guide/mcp-clients.md b/docs/guide/mcp-clients.md
index 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 waived
diff --git a/docs/guide/pair.md b/docs/guide/pair.md
index 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 only
when 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 sync
paired: 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 newer
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 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.md
index 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*, *s
A 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 the
failure.
The bias is deliberate: escalating something the browser could have handled costs a round trip;
@@ -45,7 +45,7 @@ sequenceDiagram
participant B as Background SW
participant D as Daemon
participant K as claude -p
- participant M as browsentic-mcp (child)
+ participant M as browsentic mcp (child)
S->>B: instruction + the tab it was typed on
B->>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 run
reuse 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 every
diff --git a/docs/internals/contributing.md b/docs/internals/contributing.md
index 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 memory
The 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. The
diff --git a/docs/internals/overview.md b/docs/internals/overview.md
index 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 the
exact tool surface an external client gets while still being [gated differently](guardrails.md).
---
diff --git a/docs/internals/registry.md b/docs/internals/registry.md
index 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 the
daemon'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** — the
browser is the authority on what the browser can do;
3. broadcasts `manifest-changed` to control clients, which makes each MCP server emit
diff --git a/docs/internals/request-path.md b/docs/internals/request-path.md
index 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.
```mermaid
sequenceDiagram
participant C as MCP client
- participant M as browsentic-mcp
+ participant M as browsentic mcp
participant D as Daemon
participant B as Background SW
participant 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 the
pid is alive and `/health` answers, and otherwise spawns a detached `daemon-main.js`, polling for up
to 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's
diff --git a/docs/internals/state.md b/docs/internals/state.md
index 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.md
index 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 turn
ordered, named steps. That call cannot reach the browser — `{"mcpServers":{}}` is asserted in its
argv.
-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 not
list them and why `page_listRecordings` / `page_readRecording` exist as tools.
---
diff --git a/docs/internals/transport.md b/docs/internals/transport.md
index 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 the
ambiguous 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 the
three 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 origin
and returns it XORed with a keystream derived from the same secret, so the long-lived credential
never 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 matters
diff --git a/docs/reference/README.md b/docs/reference/README.md
index 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). The
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 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.md
index 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 |
## Guardrails
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
index 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, the
daemon 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.tsx
index 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.ts
index 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; e
pairingResult = 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.ts
index 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.ts
index 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.mjs
index 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.mjs
index 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
`);