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: publish architecture, installation and feature guides
Shahriarb8fbbc05a0a1
diff --git a/README.md b/README.mdindex 5bf5d51..6225c84 100644--- a/README.md+++ b/README.md@@ -20,6 +20,14 @@ It runs on **your own [Claude Code](https://claude.com/claude-code) login**. The- **Works as an MCP server.** Claude Code or any other MCP client can drive your real, logged in browser through the same local daemon.- **Off by default.** A fresh install connects to nothing until you redeem a one time pairing code.+## Documentation++This README is the short version. The long ones live in [`docs/`](docs/):++- [Installation](docs/installation.md) — prerequisites, setup, configuration, limitations, troubleshooting, and driving Browsentic from a non-Claude agent+- [Features](docs/features.md) — every capability and when to reach for it+- [Architecture](docs/architecture.md) — how an instruction becomes a click, end to end+## How it works```diff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 0000000..66d12b2--- /dev/null+++ b/docs/README.md@@ -0,0 +1,16 @@+# Browsentic documentation++Browsentic hands your real, logged-in browser to the AI agent you already run — by voice, by typing,+or by showing it once — and turns that into real actions on the tab in front of you.++| Document | Read it for |+| --- | --- |+| [Installation](installation.md) | Prerequisites, setup, pairing, configuration, limitations, troubleshooting, and how to drive Browsentic from Codex, Gemini CLI or any other MCP client |+| [Features](features.md) | What it can do — page capabilities, instant commands, background monitoring, site maps, recordings, skills, approvals |+| [Architecture](architecture.md) | How an instruction becomes a click, end to end — processes, transport, authorization, the shared action registry, the gates |++New here? [Installation](installation.md) first, then [Features](features.md).++Extending it? [Architecture § Adding a capability](architecture.md#13-adding-a-capability).++The [project README](../README.md) is the short version of all three.diff --git a/docs/architecture.md b/docs/architecture.mdnew file mode 100644index 0000000..267e302--- /dev/null+++ b/docs/architecture.md@@ -0,0 +1,502 @@+# Architecture++How an instruction becomes a click, end to end.++Browsentic is four processes cooperating over loopback: a browser extension, a local daemon, one+stdio MCP server per client, and — when the side panel is driving — a headless Claude Code. This+document follows a request through all of them, then covers the pieces that make that path safe:+authorization, the shared action registry, the gates, and the state on disk.++---++## 1. Why there is a daemon at all++A Manifest V3 service worker cannot listen for connections. It can only dial out, and it is killed+and revived at the browser's discretion. So the extension is a *client*, and something outside the+browser has to be the meeting point.++That something is the daemon. It owns exactly one live browser link and fans it out to however many+MCP clients want a turn:++```+You ──speak or type──> Extension ──local WebSocket──> Daemon ──spawns──> your Claude Code+ ▲ │+ └──────────────── page actions ─────────────────────┘++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+component.++---++## 2. The four processes++| Process | Started by | Lives for | Job |+| --- | --- | --- | --- |+| **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. |+| **Agent** (`claude -p`) | The daemon, per side-panel instruction | One instruction | Reasons about the instruction and calls page tools. Sandboxed to Browsentic's own MCP server. |++The MCP server is deliberately thin: it holds no browser state. Kill it and the browser link is+untouched, because the link belongs to the daemon.++---++## 3. Transport and authorization++The daemon runs one HTTP server that answers `GET /health` and upgrades everything else to a+WebSocket. It binds the first free port of **8765, 8766, 8767**.++Every upgrade is classified by the handshake `Origin` header before anything else happens:++| `Origin` | Role | Requirement |+| --- | --- | --- |+| `chrome-extension://…`, `moz-extension://…`, `safari-web-extension://…` | `extension` | A pairing token or a session key bound to that same origin |+| Any other value | — | **Refused.** This is what keeps web pages out. |+| Absent | `control` | `Authorization: Bearer <token>` matching the lockfile, compared with `timingSafeEqual` |++The split matters because any web page can open a WebSocket to loopback. Browsers set `Origin`+themselves and page JavaScript cannot forge it, so a page reaching the daemon is classified as a web+origin and rejected outright. Native clients send no `Origin`, so they land in the control lane —+where a token they could only have read off the local filesystem is required.++Two independent gates, then: the origin says *what kind of peer this is*, and the credential says+*whether this particular peer is allowed*.++### The control token++Generated once (24 random bytes, base64url) and written to `~/.browsentic/daemon.json` with mode+`0600`. A restarted daemon reuses the previous token, so MCP clients survive daemon restarts. Read+it with `browsentic-mcp token`.++### Pairing and sessions++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+ ambiguous glyphs removed, valid **10 minutes**, single use.+2. You paste it into the Browsentic popup. The extension dials `ws://127.0.0.1:<port>/extension`,+ walking the three ports until one answers, and sends a `hello` frame carrying the pairing token.+3. The daemon consumes the code and mints a **session key** (32 random bytes) bound to that+ extension origin, returned in the `welcome` frame and stored in `browser.storage.local`.+4. Every later connection presents the session key instead. It survives browser and daemon restarts+ and dies only when you `browsentic-mcp revoke`.++Reconnection is exponential backoff from 1 s to 30 s with jitter, plus a one-minute+`browser.alarms` tick that re-dials if the service worker was torn down in between.++A rejected `hello` comes back as an `unauthorized` frame carrying a `retryable` flag. A wrong or+expired code is retryable and leaves the stored key alone; a revoked session is not, and the+extension discards its key rather than retrying forever.++### Protocol version++Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **7**). A mismatch closes the socket with+an explicit reason instead of letting two incompatible frame vocabularies talk past each other.++---++## 4. One registry, two bundles++There are 28 page capabilities. They are defined once, in `lib/actions/registry.ts`, and that array+is compiled into **both** the extension and the daemon.++Each action is a small module — a name, a description, a zod input schema, and an `execute()`:++```ts+export const clickElement = defineAction({+ name: 'page.clickElement',+ description: '…',+ input: z.object({ target: targetSchema.describe('…') }),+ execute({ target }) { /* runs in the page */ },+});+```++`describeActions()` turns that array into tool descriptors by converting each zod schema to JSON+Schema. The daemon serves those descriptors to MCP clients, so **an MCP tool cannot describe a+capability the browser does not have** — they are generated from the same source.++### Names++Action names are dotted (`page.getPageInfo`); MCP tool names are underscored (`page_getPageInfo`).+The mapping is mechanical, and `assertToolNamesRoundTrip()` runs on every `tools/list` to prove that+every name survives the round trip and that no two actions collide. That check is why action names+must not contain underscores — `page.get_info` would come back as `page.get.info`.++### Drift detection++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`),+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+ `notifications/tools/list_changed`.++So a half-rebuilt install degrades into "the tools the browser really has", loudly, rather than into+tool calls that fail at the far end.++### Reserved actions++Four names under the `browsentic.` prefix are not page actions:+`browsentic.saveSiteMap`, `browsentic.startRecording`, `browsentic.stopRecording`,+`browsentic.readSitemap`. The daemon refuses any invoke whose action starts with that prefix, so+they are unreachable from an ordinary MCP client. `browsentic_saveSiteMap` is published as a tool+only to the MCP server spawned inside an agent run.++`browsentic_status` is likewise not in the registry — the MCP server answers it directly by+combining daemon state with a one-element `page.getPageInfo` and the current monitor list.++---++## 5. Path A — an MCP client drives the browser++```mermaid+sequenceDiagram+ participant C as MCP client+ participant M as browsentic-mcp+ participant D as Daemon+ participant B as Background SW+ participant P as Content script++ C->>M: tools/call page_clickElement+ M->>D: {op:"invoke", action:"page.clickElement"} (control WS)+ D->>B: {t:"invoke", id, action, input} (extension WS)+ Note over D,B: also emits a timeline event so the user sees it+ B->>P: tabs.sendMessage → dispatch()+ P->>P: zod parse → execute() in the page+ P-->>B: ActionResult+ B-->>D: {t:"result", id, result}+ D-->>M: {op:"invoke", result}+ M-->>C: content[] or isError+```++Details worth knowing:++- **`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.+- **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+ timeline. It does **not** pass the approval gate — that gate applies to agent runs only.+- **Timeouts are per action, not global.** The control request waits 60 s by default; the+ extension link allows 120 s for a screenshot, the computed typing duration plus 30 s for+ `page.typeText`, any declared `timeoutMs` plus 5 s, and 30 s otherwise.+- **Screenshots are persisted by the daemon**, not the browser. `persistScreenshot()` decodes the+ data URL and writes it to `screenshotDir` (default `~/browsentic/screenshot`) at mode `0600`,+ then adds `savedTo` to the result. A failed write becomes `saveError` — the capture still+ succeeds.+- **Three read-only resources** (`browsentic://page/current`, `/diagram`, `/text`) give an MCP+ client page context without spending a tool call. They *throw* on failure rather than returning+ an error result, because MCP resources have no error channel.++---++## 6. Inside the browser: background vs content script++Not every capability can run in the page. The background service worker splits them:++| Handled entirely in the background | Why |+| --- | --- |+| `listFiles`, `attachFile`, `listRecordings`, `readRecording` | The data lives in extension storage |+| `startMonitor`, `monitorStatus`, `awaitMonitor`, `stopMonitor` | Monitors outlive any single page |+| `openTab`, `switchTab`, `closeTab`, `screenshot`, `navigate` | Need the `tabs`/`scripting` APIs |+| Everything else | Forwarded to the content script |++The forwarding call is `invokeInTab()`, and it self-heals. A tab that loaded *before* the extension+did has no content script, so `tabs.sendMessage` fails with `Receiving end does not exist`. The+extension then injects the content script via `browser.scripting.executeScript` and:++- for the four idempotent reads (`getPageInfo`, `extractText`, `waitForElement`, `navigate`) it+ retries immediately;+- for anything that *changes* the page it returns `TAB_UNREACHABLE` with instructions to re-snapshot+ first — because the caller's selectors were computed against a page it has not actually seen.++`onInstalled` also sweeps every open, non-discarded tab and injects there, so a fresh install does+not leave you with a browser full of unreachable tabs.++Pages that refuse content scripts at all (`chrome://`, the Web Store, the new-tab page) stay+`TAB_UNREACHABLE` permanently. `page_navigate` still works there through the tabs API, which is why+it is the documented escape hatch.++### Tab scoping++Every action targets the active tab of the current window unless a `tabId` is threaded through — the+one caller that does is a site-mapping run, which pins itself to the tab it started in and fails+with `MAPPING_TAB_CHANGED` if that tab goes away.++---++## 7. Path B — the side panel drives the browser++An instruction typed or spoken into the side panel takes a longer road, and it does not always+leave the browser.++### 7a. The intent funnel++`lib/intent/` scores the utterance against a local grammar first. Rules carry a `certainty`, slot+extraction returns a `confidence`, and the product must clear **0.75** to act locally.++Before scoring, four categories escalate unconditionally: anything starting with `@` (an explicit+skill pin), questions, multi-step phrasing (`and then`, `after that`), and hedges (`if`, `unless`,+`try to`). A matched rule flagged `risky` — the label contains *buy*, *pay*, *delete*, *send*,+*submit*, *confirm* and friends — escalates too.++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+failure.++The bias is deliberate: escalating something the browser could have handled costs a round trip;+acting on something misread spends a wrong click on a real page.++### 7b. The agent run++```mermaid+sequenceDiagram+ participant S as Side panel+ participant B as Background SW+ participant D as Daemon+ participant K as claude -p+ participant M as browsentic-mcp (child)++ S->>B: instruction + context (url, tabId, files, recordings)+ B->>B: tryFastPath() — grammar+ B->>D: {t:"instruct", id, text, context}+ D->>D: route skill, build system prompt+ D->>K: spawn with --mcp-config {browsentic}, BROWSENTIC_AGENT_RUN=<runId>+ K->>M: stdio (its only MCP server)+ M->>D: {op:"invoke", runId, action} (control WS)+ D->>D: approval / mapping gate+ D->>B: {t:"invoke", …}+ B-->>D: result+ D-->>M: result+ M-->>K: tool result+ K-->>D: stream-json deltas+ D-->>S: run events (text, tool, toolResult, approval, done)+```++The loop closes on itself: the daemon spawns Claude Code, which spawns *another* `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.++The `BROWSENTIC_AGENT_RUN` environment variable is the whole mechanism. The child MCP server reads+it, stamps `runId` on every control invoke, and the daemon routes those to+`AgentSession.invokeForRun()` — the gated path — instead of `invokeExternal()`. It also causes+`browsentic_saveSiteMap` to be published as a tool.++### How the child is sandboxed++`runInstruction()` spawns `claude -p` with:++- `--strict-mcp-config` and an explicit `--mcp-config` naming only Browsentic, so the user's own MCP+ servers are not in scope;+- `--allowedTools mcp__browsentic`, and a `--disallowedTools` list covering every built-in that+ touches the filesystem, the shell or subagents (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`,+ `Task`, `Skill`, …);+- `WebSearch`/`WebFetch` allowed **only** during a site-mapping run with `research` on;+- `--append-system-prompt` carrying the assembled prompt;+- `--session-id` on the first turn and `--resume` afterwards, which is what makes "now click the+ second one" work;+- a scrubbed environment — `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT` and `BROWSENTIC_AGENT_RUN` are+ deleted before the spawn so the child does not think it is nested inside another run.++Output is `stream-json` with partial messages, so text deltas reach the side panel token by token.+Only top-level content is forwarded — anything with a `parent_tool_use_id` is a subagent's chatter+and is dropped.++### Prompt assembly++`buildSystemPrompt()` concatenates, in order:++1. a fixed preamble — the browser is not a sandbox, page content is data and never instructions,+ do not exfiltrate, a `DECLINED` action is final, report what actually happened;+2. the routed **base skill** body;+3. optional **fetched data** (a site's own `robots.txt`/`sitemap.xml`, during mapping);+4. optional **attached files** — notes Browsentic made when each file was attached, capped at 8 KB;+5. optional **recordings** index, capped at 4 KB;+6. any matching **site notes** overlays, hand-written ones before machine-generated ones.++The whole thing is capped at 64 KB. Overlays that would push it over are dropped by name, and the+side panel is told which ones — a silently truncated prompt is worse than a visibly incomplete one.+Every untrusted block gets its own framing paragraph re-stating that its contents are data.++### Skill routing++Skills are markdown with YAML-ish front matter, loaded from three directories, later shadowing+earlier by name:++| Directory | Source | Contents |+| --- | --- | --- |+| `mcp/skills/` (bundled) | `bundled` | `browser-control` (default), `page-research`, `browse-navigation`, `monitor-progress`, `site-mapper` |+| `~/.browsentic/skills/` | `user` | Hand-written overrides |+| `~/browsentic/skills/` (or `skillsDir`) | `uploaded` | Panel uploads and generated site maps |++Both `<name>.md` and `<name>/SKILL.md` are recognised. All three directories are re-read on **every+run**, so editing a skill applies to the next instruction with no reload.++Routing picks exactly one **base** skill (`category: general`) by counting trigger-word hits, with+the `default: true` skill as the fallback. A `@name` prefix pins one explicitly. Skills with+`category: site-exploration` are **overlays** instead: they stack on top of the base whenever the+active tab's host matches their `domains`, longest match first.++---++## 8. The gates++Three distinct mechanisms, often confused:++**Approval.** `requireApproval` in `config.json` (default `["page.submitForm"]`) names actions that+pause an agent run for an explicit Allow or Deny in the side panel. It is smarter than a name match:+listing `page.submitForm` also catches `page.fillInput`/`page.typeText` with `pressEnter: true` and+`page.pressKey` with `Enter`, because those submit forms too. A denial returns `DECLINED` with+instructions not to seek another route to the same effect. **Approval applies to agent runs only** —+direct MCP invocations bypass it, by design, because the MCP client has its own permission system.++**Mapping.** A site-mapping run is gated far harder, and the gate lives in the daemon rather than in+the prompt. Only ten read-only actions are reachable (`MAPPING_READ_ONLY` otherwise); navigation must+be an absolute URL on the mapped origin (`MAPPING_OFF_SITE` for anything else, including `back` and+`forward`, which walk history off-site); page and screenshot budgets are enforced+(`MAPPING_BUDGET`); and the run is pinned to one tab. Drifting off-host blocks every read until it+navigates back.++**Reserved prefix.** The daemon's `invoke()` refuses anything under `browsentic.` outright, so the+mapping and recording control actions are not reachable as ordinary tools.++Config can narrow the mapping limits but never widen them past the compiled ceilings:++| Setting | Default | Ceiling |+| --- | --- | --- |+| `maxPages` | 15 | 40 |+| `maxScreenshots` | 10 | 24 |+| `timeoutMs` | 600 000 (10 min) | 1 800 000 (30 min) |++---++## 9. Subsystems++**Monitors** (`lib/monitor/`, `lib/bridge/monitor.ts`) watch a pinned tab in the background for a+completion condition — an element appearing or vanishing, text or title matching a regex, a progress+bar reaching a threshold. Up to 3 at once, 30 minutes by default and 4 hours maximum, with percent+and ETA extrapolated from the sample history. Completion fires a browser notification; an MCP client+can also long-poll with `page_awaitMonitor`. Sampling is debounced and rate-limited, with a 5-second+backstop tick so a page that stops mutating still gets checked.++**Recordings** (`lib/recordings/`) are the reverse of a monitor: the content script observes what+*you* do in one pinned tab — clicks, fills, selects, keys, submits, scrolls, navigations — for at+most 15 minutes, warning at 13. Events are batched to the background. On stop, a one-shot `claude -p`+call turns the raw trace into ordered, named steps. Typed values become `{{placeholders}}` unless+"Save what I type" is on, and passwords, hidden fields, one-time codes and Luhn-valid card numbers+are dropped either way. Recordings live in extension storage, not on disk, which is why+`browsentic-mcp skills` does not list them and `page_listRecordings` / `page_readRecording` exist.++**Site maps** (`lib/skills/site-map.ts`, `mcp/src/agent/site-map-store.ts`) are generated skills. A+mapping run crawls one host read-only and finishes by calling `browsentic_saveSiteMap` once. The+report is validated against per-field size limits, then written to a `.staging/` directory the skill+loader deliberately cannot read — an unreviewed map is not merely unused, it is never opened. The+panel shows the markdown as plain text with the domain it will match; **Activate** commits it,+**Discard** deletes it. An abandoned run's staging is swept.++**Files** attached in the side panel are stored in the extension and summarised by a one-shot+`claude -p` at attach time. The agent never opens a file; it sees the notes, plus+`page_attachFile { fileId, target }` to put one into a file input.++**Screenshots** stitch `captureVisibleTab` tiles for full-page mode, capped at 48 tiles and a+16 384 px canvas side, reporting `truncated: true` when the page was taller than the limit.++---++## 10. State on disk++Nothing lives in the repository.++```+~/.browsentic/ (mode 0700, override with BROWSENTIC_HOME)+├── daemon.json 0600 lockfile: pid, port, control token, protocol + daemon version+├── auth.json 0600 outstanding pairing code, session keys per origin+├── config.json optional, hand-written+├── daemon.log run starts, routed skills, every tool call and its outcome+└── skills/ hand-written skill overrides++~/browsentic/ (paths configurable)+├── skills/ panel uploads + activated site maps+│ ├── acme-com/SKILL.md+│ └── .staging/ maps awaiting review — unreadable to the loader+└── screenshot/ 0600 every capture, unless save:false+```++Recordings are the exception: they stay in the extension's own storage.++---++## 11. Failure modes++Errors are `{ ok: false, error: { code, message } }` all the way through, surfaced to MCP clients as+`isError` with `CODE: message`. They are recoverable signals, and each implies a different next move.++| Code | Origin | Meaning |+| --- | --- | --- |+| `EXTENSION_OFFLINE` | Daemon | No live browser link. Pair, or open the browser. Retrying will not help. |+| `TAB_UNREACHABLE` | Extension | The page refuses content scripts, or one was just injected. Navigate to an http(s) page, or re-snapshot. |+| `NO_ACTIVE_TAB` | Extension | No focused tab in the current window. |+| `TARGET_NOT_FOUND` | Content script | Nothing matched. The page changed — take a fresh snapshot. |+| `INVALID_TARGET` | Content script | A target with neither `selector` nor `text`. `role`/`nth` only narrow. |+| `INVALID_INPUT` | Dispatch | zod rejected the input; the message names the field. |+| `UNSUPPORTED` | Action | e.g. a non-http(s) URL. |+| `TIMEOUT` | Link or action | A wait expired, or the extension did not answer in the window for that action. |+| `ACTION_FAILED` | Action | `execute()` threw — e.g. `back` with no history. |+| `UNKNOWN_ACTION` | Registry / daemon | Tool-registry skew, or a reserved action reached from outside. |+| `DAEMON_UNREACHABLE` | RemoteBridge | The daemon died mid-call. |+| `RUN_IN_PROGRESS` | AgentSession | One instruction at a time. |+| `RUN_INACTIVE` | AgentSession | The run was cancelled while a tool call was in flight. |+| `DECLINED` | Approval gate | The user said no. Final. |+| `NO_CLAUDE` | Runner | `claudeBin` is not on the daemon's PATH. |+| `MAPPING_*` | Mapping gate | Read-only, off-site, budget or tab-change refusal. |++Two design choices show up repeatedly here: failures carry the *fix* in the message, and a failed+tool call never crashes a run.++---++## 12. Build topology++Two Yarn projects with separate lockfiles.++| | Extension | Daemon + MCP |+| --- | --- | --- |+| Root | `/` | `/mcp` |+| Bundler | WXT (Vite) | tsup |+| Output | `dist/chrome-mv3` | `mcp/dist` |+| Stack | React 19, Tailwind v4, shadcn/ui, zod | Node ≥20, `@modelcontextprotocol/sdk`, `ws`, zod |+| Build | `yarn build` | `yarn mcp:build` |++`mcp/` imports `lib/` through the `@/` alias, which is how one registry ends up in two bundles.+`node scripts/setup.mjs` (`yarn setup`) runs all four steps — both installs, both builds — using the+Yarn release vendored in the repository, so a fresh clone needs nothing on `PATH` but Node.++Verify the two halves agree with `yarn mcp:manifest`, which prints the tool manifest without needing+a browser at all.++---++## 13. Adding a capability++Write `lib/actions/page/<name>.ts` and add it to the array in `lib/actions/registry.ts`. That single+edit publishes it as an MCP tool, because the daemon bundles the same registry.++Four conventions are load-bearing at runtime rather than at compile time:++1. Touch `document`/`window` only inside `execute()` — the module is also imported by the daemon,+ where there is no DOM.+2. No underscores in action names — they break the tool-name round trip.+3. `.describe()` every input field — the text becomes the tool's JSON Schema documentation.+4. Validate with `ActionError` inside `execute()`, not zod `.refine()`/`.transform()` — those do not+ survive JSON Schema conversion.++Then rebuild **both** halves and reload the extension at `chrome://extensions`; Chrome does not+auto-reload unpacked extensions, and a stale service worker is the usual cause of a drifted+manifest.diff --git a/docs/features.md b/docs/features.mdnew file mode 100644index 0000000..5c10a07--- /dev/null+++ b/docs/features.md@@ -0,0 +1,388 @@+# Features++What Browsentic can do, and when each part is the right tool.++Browsentic hands your real, logged-in browser to the AI agent you already run. Say what you want and+it drives the page; ask a question and it reads the page and answers. Everything it does shows up on+a live timeline, and anything consequential waits for your approval first.++---++## Two ways to drive++| | Side panel | MCP client |+| --- | --- | --- |+| You talk to | Browsentic, by voice or typing | Claude Code, Codex, Gemini CLI, Cursor, … |+| Agent | Claude Code, spawned locally by the daemon | Whichever client you registered |+| Skills and site notes | Routed and applied automatically | Not applied |+| Approval prompts | Yes | Your client's own permissions |+| Recording, site mapping | Full access | Read-only |++Both land on the same browser through the same daemon, so you can move between them mid-task.++---++## Voice and text++Dictate hands-free in the side panel, press-to-talk in the popup, or just type. Speech uses the+browser's built-in recognition — nothing is bundled or downloaded. In Chrome that means audio is+streamed to Google for transcription; type instead if that matters to you.++Replies stream back token by token. Follow-ups continue the same conversation, so **"now click the+second one"** works. Conversations are saved, named automatically, and reopenable from the panel's+history.++---++## Page capabilities++28 actions, published to MCP clients as 28 tools generated from the same registry the extension+ships — so a tool can never describe something the browser cannot do.++### Reading++| Tool | What it does |+| --- | --- |+| `page_getPageInfo` | The workhorse. Document metadata, viewport and scroll state, a semantic layout tree with a text diagram, the heading outline, and an inventory of links, buttons, fields and forms — **each with a stable selector already computed**. |+| `page_extractText` | Rendered text, or raw HTML, of an element or the whole page. |+| `page_waitForElement` | Wait until an element is attached, visible, hidden or detached. |+| `page_screenshot` | The full scroll view, the current viewport, or one element. Saved to disk automatically. |+| `page_findProgress` | Scan for progress signals worth monitoring — bars, percent readouts, spinners — each with a selector. |++Start with `getPageInfo` and use the selectors it hands back rather than guessing. Better still,+target by **visible text** — it survives redesigns that break CSS paths.++### Acting++| Tool | What it does |+| --- | --- |+| `page_clickElement` | Clicks like a user, firing the full pointer and mouse sequence. |+| `page_hoverElement` | Triggers menus, tooltips and hover states. |+| `page_focusInput` | Focus and place the caret, or select all. |+| `page_fillInput` | Set a value in an input, textarea or contenteditable. |+| `page_typeText` | Streams text one keystroke at a time at a human pace — a real key event per character, varying pauses, longer breaths after punctuation. For pages that *watch* you type. |+| `page_selectOption` | Choose a `<select>` option by value, label or position. |+| `page_selectText` | Select text by element or exact phrase. |+| `page_pressKey` | A key press with optional modifiers. |+| `page_submitForm` | Submit a form, firing its validation as if you pressed Enter. |+| `page_highlightElement` | A temporary outline overlay with an optional caption — for showing you what it found. |++### Moving++| Tool | What it does |+| --- | --- |+| `page_navigate` | Go to a URL, or back / forward / reload. |+| `page_scrollTo` | To an element, an absolute position, or by one viewport. |+| `page_openTab` | Open a URL in a new tab, which becomes the target for later actions unless `active: false`. |+| `page_switchTab` | Bring another tab to the front. With no arguments it *lists* the open tabs and their ids. |+| `page_closeTab` | Close a tab and report which one the browser moved to. |++Tab tools are the only ones that change *which* tab everything else acts on, and they are scoped to+the current window. `closeTab` refuses deliberately in four cases: the only tab in a window, a+pinned tab, a browser page, and a tab being recorded.++### Files++`page_listFiles` and `page_attachFile` let the agent put a file you have stored in Browsentic into+a file input on the page. Files are summarised by a one-shot local read when you attach them, so the+agent knows what it is uploading without being able to open your filesystem.++### Recordings++`page_listRecordings` and `page_readRecording` read back the browsing sessions you recorded — see+[Recordings](#recordings-show-it-once-repeat-it-later).++Most capabilities take a target described by **CSS selector, visible text, ARIA role or index**.++---++## Instant commands++Sending "go back" out to a language model costs a round trip and several seconds to arrive at+something the extension could have done immediately. So every instruction is scored against a local+grammar first. Confident single-step commands run in the browser in milliseconds and stop there,+marked with a ⚡ on the timeline. Everything else goes to the agent with the text untouched.++| Runs locally | Goes to the agent |+| --- | --- |+| back, forward, reload | "is there a login button?" |+| open github.com, open localhost:3000 | "open the settings menu" |+| open github.com in a new tab | "close this tab", "switch to my gmail tab" |+| google something, search the web for something | "search for wireless headphones" |+| scroll up, down, top, bottom, page down | "scroll down and tell me what it says" |+| press enter, hit escape, press arrow down | "click sign in and then fill in my email" |+| click Sign in, tap Continue | "click Buy now", "click it" |+| record my browsing session, stop recording | "record a video of this page" |+| stop monitoring | "stop watching and tell me what happened" |++The bias is toward escalating, because the two mistakes are not symmetric. Escalating something it+could have handled costs a round trip. Acting on something it misread spends a wrong click on your+real page. Questions, multi-step asks, conditionals, vague targets and consequential clicks all+escalate — as does any local command that runs and fails.++Local commands never reach the daemon, so they leave no trace in `browsentic-mcp logs`. That is+expected, not a bug. Explain any single routing decision with:++```sh+yarn intent:check "take me to the checkout page"+```++---++## Background monitoring++Long jobs — an upload, a build, a deploy — do not need an agent sitting on them burning tokens on+"is it done yet".++Ask Browsentic to watch, and it finds the progress signal (`page_findProgress`), pins the tab, and+watches it in the background while you work elsewhere. It tracks percent, extrapolates an ETA from+the sample history, notices when progress has stalled, and notifies you on completion.++```+watch this upload and tell me when it's done+```++| | |+| --- | --- |+| Completion conditions | An element appears or vanishes, page text or tab title matches a regex, a progress bar reaches a threshold |+| Concurrent monitors | 3 |+| Default / maximum duration | 30 minutes / 4 hours |+| While it runs | The tab is pinned; you can work anywhere else |+| On completion | A browser notification, plus the run's own report |++An MCP client can also block on one with `page_awaitMonitor`, which long-polls: `settled: false`+just means the poll window passed while the watch continues, so call again. The monitor keeps+running in the browser even if the client disconnects.++`stop monitoring` ends one without waking the agent at all.++---++## Site maps: teach it a site once++An agent that has never seen your site spends its first minutes rediscovering it — where search+lives, what a button is really called, why the list looks empty until you scroll. Site maps do that+exploration once and keep the result.++Press **Map** in the Skills panel, or say:++```+@site-mapper map this site+```++Browsentic reads the site's own `robots.txt` and `sitemap.xml`, looks up public background on the+domain, then walks the site for a few minutes taking screenshots. The result is a set of notes+scoped to that domain:++```+~/browsentic/skills/acme-com/+├── SKILL.md landmarks, key pages, how they connect, quirks+├── map.json the structured report behind it+├── screenshots/ captures taken during the crawl+├── evidence/ the robots.txt and sitemap it worked from+└── pages/ longer per-page notes, kept out of the prompt+```++From then on, any instruction you give on that domain carries those notes. Elsewhere they are inert.++**Nothing takes effect until you say so.** A map in flight is written to a staging directory the+skill loader cannot read, so an unreviewed map is not merely unused — it is never opened. The panel+shows you the exact markdown as plain text, never rendered, along with the domain it will match.+**Activate** arms it; **Discard** deletes it.++The crawl is read-only and locked to one host. It cannot click, fill or submit; it cannot leave the+site; and it is pinned to the tab it started in, so switching tabs stops it rather than following+you. Limits are enforced by the daemon, and config can narrow them but never widen them:++| Setting | Default | Ceiling |+| --- | --- | --- |+| `maxPages` | 15 | 40 |+| `maxScreenshots` | 10 | 24 |+| `timeoutMs` | 600 000 (10 min) | 1 800 000 (30 min) |++Two switches change what a mapping run may do. `allowClicks` (off by default) lets it reach routes+that only exist behind an interaction. `research` (on by default) lets it use web search for public+background on the domain.++> A map is written from pages an agent read, so read it before activating, as you would any+> generated content. `research` is the one case where a run both reads pages and makes outbound+> requests; turn it off to keep everything inside the browser.++Mapping requires the explicit `@site-mapper` prefix or the Map button — trigger words alone will not+start one, because a mapping run takes minutes and commandeers the tab.++### Writing notes by hand++If you would rather describe a site yourself, upload a markdown file from the side panel composer:++```markdown+---+name: acme-admin+description: Our internal admin tool.+category: site-exploration+domains: [admin.acme.com]+---++Search is `#q` and submits on Enter, not on the button.+Results lazy load. Click "Load more" until it disappears before counting anything.+```++Notes are **overlays**, not replacements: on a matching site they stack on top of whatever+Browsentic was already doing, so the normal driving and read-only rules still apply. Prefix an+instruction with `@acme-admin` to pin one regardless of where you are.++Notes live outside the repository, are re-read on every run so an edit applies to the next thing you+ask, and `browsentic-mcp skills` lists everything currently in scope.++---++## Recordings: show it once, repeat it later++A site map teaches Browsentic what a site **is**. A recording teaches it what **you do** there.++Press the red record button in the composer, do the job yourself — click through the pages, fill the+fields, submit the form — and press stop. Browsentic splits what you did into ordered steps, names+them after what you accomplished, and keeps them in a renameable list. Later, "do it like last time"+runs them again. You can also just say it:++```+record my browsing session+stop recording+```++A recording follows the tab it started in and nothing else. Navigations inside that tab become+steps, other tabs are ignored, and closing the tab stops and saves. It runs for at most **15+minutes**, warns you at 13, and stops itself at the limit.++**What you type is not saved by default.** Every field becomes a placeholder — `{{email}}`,+`{{invoice_number}}` — and the assistant asks you for the value when it replays. Tick **Save what I+type** to keep literal values instead; passwords, hidden fields, one-time codes and anything shaped+like a card number are dropped either way.++Replaying is not blind playback. The steps are a plan, not a script: the agent re-checks each target+against the live page before acting, and prefers the visible text it recorded over the CSS selector,+because selectors are what a redesign breaks first. Anything consequential still waits for approval,+even though you performed it yourself while recording. If a step no longer lands, the run stops and+tells you which one rather than improvising a different route to the same effect.++Recordings live in the extension's own storage rather than on disk, so `browsentic-mcp skills` does+not list them. The one time a recording leaves the browser is the local call that turns the raw+trace into steps.++---++## Skills++Every side-panel instruction is routed to exactly one **base skill**, chosen by trigger words:++| Skill | Handles |+| --- | --- |+| `browser-control` *(default)* | Drive the open tab — click, type, submit, navigate, verify |+| `page-research` | Read and summarise without changing anything |+| `browse-navigation` | Replay a recorded session — "do it like last time" |+| `monitor-progress` | Watch a long-running task and report when it finishes |+| `site-mapper` | Walk a site and write up how it is laid out |++Skills are plain markdown. Drop your own into `~/.browsentic/skills/`, or upload one from the panel,+and it shadows a bundled skill of the same name. All three skill directories are re-read on every+run, so an edit applies to the very next instruction.++`browsentic-mcp skills` prints everything the router can see, tagged with where it came from.++---++## Screenshots++Full scroll view by default; `fullPage: false` for the viewport, or a `target` for one element or+block. Every capture is written to `~/browsentic/screenshot/` (mode `0600`) unless you pass+`save: false`, and the result reports the path as `savedTo`.++Very tall pages are stitched from viewport tiles and capped — beyond the limit the bottom is cut off+and the result says `truncated: true`, rather than silently returning a partial image.++---++## Files++Attach a file in the side panel and Browsentic reads it once, at attach time, and keeps notes. The+agent sees those notes — never your filesystem — plus two tools: `page_listFiles` to re-read the+list and `page_attachFile` to put one into a file input on the page. Uploading is treated as+consequential.++---++## The timeline and approvals++Every action appears as it happens, with what it targeted and what came back. Local commands carry+a ⚡; actions from an MCP client are tagged as external. Cancelling stops a run mid-flight.++Actions that change something other people can see wait for an explicit **Allow** or **Deny**. Form+submission is gated by default, and the gate is smarter than a name match — it also catches+`fillInput`/`typeText` with `pressEnter: true` and pressing Enter, because those submit forms too.+Denying is final: the agent is told to report it and stop, not to find another route to the same+effect.++Add more actions to `requireApproval` in `~/.browsentic/config.json` if you want them gated. The+cost of a longer list is a longer list — a prompt you see on every other tool call is a prompt you+stop reading.++---++## For MCP clients++```sh+claude mcp add browsentic -- browsentic-mcp+```++Your client gets the 28 page tools, plus:++**`browsentic_status`** — whether the extension is connected, its version, the active tab, any+running monitors, and a `hint` naming the fix when something is wrong. Call it first when a page+tool fails.++**Three read-only resources** that return page context without spending a tool call:++| Resource | Use when |+| --- | --- |+| `browsentic://page/diagram` | You just need the page's shape — the cheapest useful view |+| `browsentic://page/current` | The full `getPageInfo` snapshot as JSON |+| `browsentic://page/text` | You only need the rendered prose |++The tool list is generated from the same registry the extension ships, so it cannot drift from what+the browser can actually do — and if the two halves *are* built from different registries, the+daemon adopts the browser's list and tells your client the tools changed.++Several clients can be registered at once. They share one daemon and one browser, so they interleave:+tool calls stay correctly correlated, but page state can shift under either of them.++---++## Privacy and security++- **Nothing connects until you pair.** A fresh install contacts nothing until you redeem a one-time+ code.+- **Two independent gates.** Any web page can open a WebSocket to loopback, so the daemon first+ classifies the peer by handshake `Origin` — which browsers set themselves and pages cannot forge —+ then requires a pairing token or an origin-bound session key. A web page can never reach the+ control path.+- **Consequential actions ask first**, named in the prompt, in the side panel.+- **Recordings capture what you do, not what you type.** Literal values are opt-in per recording;+ passwords, hidden fields, one-time codes and card numbers are never stored either way. Recording+ only ever starts from your own click or your own words.+- **Agent runs are sandboxed.** The spawned agent gets Browsentic's tools and nothing else — no+ shell, no filesystem, no other MCP servers, and no web access unless a mapping run asked for it.+- **State stays outside the repository**, under `~/.browsentic` and `~/browsentic`.++Two limits worth stating plainly. Pairing controls **which browser**, not which local process:+anything running as your user can read the daemon lockfile and drive an already-paired browser. And+an agent reading a hostile page is still susceptible to prompt injection, so treat page content as+data, never as instructions.++Full list in [installation.md § Limitations](installation.md#limitations).++---++## See also++- [architecture.md](architecture.md) — how the pieces fit together+- [installation.md](installation.md) — prerequisites, setup, configuration, agent switchingdiff --git a/docs/installation.md b/docs/installation.mdnew file mode 100644index 0000000..55a5762--- /dev/null+++ b/docs/installation.md@@ -0,0 +1,421 @@+# Installation++Browsentic is two halves — a browser extension and a local daemon — plus a pairing step that+connects them. Budget about five minutes.++There is no account, no API key and no cloud service. Browsentic drives your real browser using the+AI agent you already run locally.++---++## Prerequisites++| | Requirement | Check |+| --- | --- | --- |+| **Node** | 20 or newer | `node --version` |+| **Browser** | Chrome, or another Chromium browser (Edge, Brave, Arc). Firefox has a build target. | — |+| **Agent** | [Claude Code](https://claude.com/claude-code) on your `PATH`, logged in | `claude --version` |+| **git** | To clone the repository | `git --version` |++Notes:++- **Claude Code is required for the side panel**, and only 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 never spawns anything and Claude Code is optional — see+ [Using a different agent](#using-a-different-agent).+- **Keep Claude Code reasonably current.** Browsentic passes flags that sandbox the run+ (`--strict-mcp-config`, `--disallowedTools`, `--append-system-prompt`). An older build that does+ not understand them fails the run with an explicit "update Claude Code" message rather than+ running unsandboxed.+- **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++```sh+git clone https://github.com/imshaikot/browsentic.git+cd browsentic+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.++When it finishes you have:++```+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.++For 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.++## 3. Put the CLI on your PATH++```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:++```sh+browsentic-mcp --version+```++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.++## 4. Pair your browser++```sh+browsentic-mcp pair+```++This starts the daemon if it is not already running and prints a code:++```+ Pairing code: K7QM-3XPT++ Open the Browsentic popup, paste it, and press Connect.+ Expires in 10 minutes and works once.+```++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.++Verify:++```sh+browsentic-mcp status+```++```+daemon: running on 127.0.0.1:8765 (pid 41207, v0.1.7)+extension: connected (v0.1.7)+manifest: in sync+paired: 1+```++Open the side panel and start talking. That is the whole setup.++---++## 5. Register with an MCP client (optional)++Pairing connects your browser to the daemon. Registering an MCP client lets *that client* drive the+same browser.++**Claude Code:**++```sh+claude mcp add browsentic -- browsentic-mcp+```++**Any other stdio MCP client** — the command is always `browsentic-mcp` with no arguments. Most+clients take a JSON block of this shape:++```json+{+ "mcpServers": {+ "browsentic": { "command": "browsentic-mcp" }+ }+}+```++Codex CLI uses TOML in `~/.codex/config.toml` instead:++```toml+[mcp_servers.browsentic]+command = "browsentic-mcp"+```++Check your client's own documentation for the exact file and key — the *command* is the part that+matters, and it is the same everywhere.++The client then gets 28 page tools, `browsentic_status`, and three read-only resources.+**MCP servers are loaded at session start**, so restart the client session after registering.++---++## Using a different agent++Worth being precise here, because Browsentic has two independent agent surfaces and only one of them+is switchable.++### The side panel: Claude Code only++The in-extension agent spawns `claude -p` and speaks Claude Code's CLI protocol — `stream-json`+output, `--mcp-config`, `--allowedTools`, `--session-id`/`--resume`, `--append-system-prompt`. There+is no adapter for Codex, Gemini CLI or any other agent, and pointing `claudeBin` at a different+binary will not work: it would be handed flags it does not understand.++What you *can* change is which Claude runs it, in `~/.browsentic/config.json`:++```json+{+ "claudeBin": "/opt/homebrew/bin/claude",+ "model": "claude-sonnet-5",+ "effort": "high"+}+```++| Key | Default | Effect |+| --- | --- | --- |+| `claudeBin` | `claude` | Path to the Claude Code binary. Set this when the daemon's `PATH` differs from your shell's — the usual cause of `NO_CLAUDE`. |+| `model` | `claude-sonnet-5` | Passed as `--model`. Use `claude-opus-5` for harder multi-step work, `claude-haiku-4-5-20251001` for speed. |+| `effort` | unset | Passed as `--effort`: `low`, `medium`, `high`, `xhigh`, `max`. |++Changes apply to the next run — the config is re-read each time, no daemon restart needed.++### Everything else: any MCP client++The other direction is fully agent-agnostic. Browsentic is a plain stdio MCP server, so **Codex CLI,+Gemini CLI, Cursor, Zed, Claude Desktop** — anything that speaks MCP — can drive your real browser+through the same daemon and the same paired session. Register it as shown+[above](#5-register-with-an-mcp-client-optional).++So the practical answer to "can I use Browsentic with Codex or Gemini?" is **yes, as an MCP client**.+You drive the browser from that agent's own interface, with its own permission prompts, rather than+from Browsentic's side panel.++The two surfaces differ in more than which model runs them:++| | Side panel (agent run) | MCP client |+| --- | --- | --- |+| Agent | Claude Code, spawned by the daemon | Whatever you registered |+| Approval gate | Yes — `requireApproval`, prompts in the panel | No — your client's own permissions apply |+| Timeline | Every action, live | Actions appear tagged `external` |+| Skills / site notes | Routed and applied automatically | Not applied |+| Recordings, site mapping | Available | Readable only (`page_listRecordings`, `page_readRecording`) |+| Appears in `browsentic-mcp logs` | Yes | Yes |+| Voice input | Yes | No |++Several clients can be registered at once. They share one daemon and one browser, so they interleave+— tool calls stay correctly correlated, but page state can shift under either of them.++---++## Configuration reference++Everything is optional. `~/.browsentic/config.json`:++```json+{+ "claudeBin": "/opt/homebrew/bin/claude",+ "model": "claude-sonnet-5",+ "effort": "high",+ "requireApproval": ["page.submitForm"],+ "screenshotDir": "~/browsentic/screenshot",+ "skillsDir": "~/browsentic/skills",+ "siteMap": {+ "research": true,+ "allowClicks": false,+ "maxPages": 15,+ "maxScreenshots": 10,+ "timeoutMs": 600000+ }+}+```++| Key | Default | Notes |+| --- | --- | --- |+| `requireApproval` | `["page.submitForm"]` | Actions an agent run must ask about first. Listing `page.submitForm` also catches `pressEnter: true` and pressing Enter, because those submit forms too. Add `"page.closeTab"` to approve each tab close, and so on — but a prompt you see on every other tool call is a prompt you stop reading. |+| `screenshotDir` | `~/browsentic/screenshot` | Where captures are written, mode `0600`. |+| `skillsDir` | `~/browsentic/skills` | Where panel uploads and generated site maps live. |+| `siteMap.research` | `true` | Lets a mapping run use web search for public background on the domain. Turn it off to keep everything inside the browser. |+| `siteMap.allowClicks` | `false` | Lets a mapping run reach routes that only exist behind an interaction. |+| `siteMap.maxPages` | 15 | Ceiling 40. |+| `siteMap.maxScreenshots` | 10 | Ceiling 24. |+| `siteMap.timeoutMs` | 600 000 | Ceiling 1 800 000 (30 min). |++Config can narrow the mapping limits but never widen them past the compiled ceilings.++`BROWSENTIC_HOME` relocates the whole state directory if you need it somewhere other than+`~/.browsentic`.++---++## Limitations++Read this section before deciding where Browsentic fits.++### It needs a real browser, open++There is no headless mode. Browsentic drives the browser you are looking at, in your real profile+with your real logins. Close the browser and every tool call returns `EXTENSION_OFFLINE`. If you+want anonymous fetching of a static page, an ordinary HTTP fetch is the right tool.++### Pages that refuse content scripts++`chrome://` pages, the Chrome Web Store and the new-tab page cannot host a content script, so most+tools return `TAB_UNREACHABLE` there. `page_navigate` still works and is the way out. Ordinary sites+self-heal: a tab that loaded before the extension did gets a content script injected on first+contact.++### One browser link, one run at a time++The daemon keeps a single live extension connection — a newer one supersedes the old. Several+browsers can be *paired*, but only one is connected at a time. Within the side panel, one+instruction runs at a time; a second returns `RUN_IN_PROGRESS`.++### Pairing controls which browser, not which process++This is the security boundary worth understanding. Pairing binds a browser. It does not+authenticate local programs: anything running as your user can read `~/.browsentic/daemon.json` and+drive an already-paired browser through the control port. Browsentic assumes your user account is+the trust boundary.++### Prompt injection is a real risk++An agent reading a hostile page is susceptible to instructions embedded in that page. Browsentic+frames all page text as untrusted data in the system prompt and re-states it around every injected+block, but this is mitigation, not a guarantee. The approval gate is the backstop: keep it on for+anything consequential, and be deliberate about running agent instructions on sites you do not+trust.++### Approval only gates agent runs++Direct MCP invocations do **not** pass the approval gate and do not appear as approval prompts —+they rely on your MCP client's own permission system. Do not assume something the side-panel agent+was denied is safe to do from an MCP client instead.++### Speech goes to Google++Voice input uses Chrome's built-in Web Speech API, which streams audio to Google for transcription.+No model is bundled and nothing is downloaded. If that is not acceptable, type instead — it is one+file to replace the speech engine.++### Recording and mapping limits++Recordings run for at most 15 minutes, follow one tab, live in extension storage rather than on+disk, and drop passwords, hidden fields, one-time codes and card numbers unconditionally. Site+mapping is read-only, locked to one host and one tab, and capped as in the table above. Mapping mode+requires the explicit `@site-mapper` prefix or the Map button — trigger words alone will not start+one.++### Screenshots of very tall pages++Full-page capture stitches viewport tiles, capped at 48 tiles and a 16 384 px canvas side. Beyond+that the bottom is cut off and the result reports `truncated: true`.++### Loopback ports++The daemon binds the first free port of 8765, 8766, 8767. If all three are taken it will not start.++### Unpacked extension++Installing from source means Chrome will not auto-update it, and will not auto-reload it after a+rebuild — you must press ↻ at `chrome://extensions`. Chrome may also prompt about developer-mode+extensions on each launch.++---++## Updating++```sh+git pull+yarn setup+```++Then reload the extension at `chrome://extensions` (↻ on the Browsentic card) and restart the+daemon:++```sh+browsentic-mcp stop+```++It restarts automatically on the next call. **Rebuild both halves together.** If only one side is+rebuilt, `browsentic-mcp status` reports `manifest: DRIFTED` — the daemon falls back to the tools+the browser actually has and tells your MCP client the list changed, but you should fix the drift+rather than run on it.++Your pairing survives updates. `yarn mcp:link` only needs re-running if the link is broken.++---++## Uninstalling++```sh+browsentic-mcp revoke # unpair every browser+browsentic-mcp stop # stop the daemon+yarn mcp:unlink # remove browsentic-mcp from PATH+rm -rf ~/.browsentic ~/browsentic+```++Then remove the extension at `chrome://extensions`. That also clears recordings and stored files,+which live in extension storage.++---++## Troubleshooting++| 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 the log with `browsentic-mcp logs` |+| Tools missing from an MCP session | The server was registered mid-session | Restart the client session — MCP servers load at start |+| `manifest: DRIFTED` | Extension and CLI built from different registries | `yarn build && yarn mcp:build`, then reload the extension |+| `NO_CLAUDE` | Claude Code is not on the daemon's `PATH` | Set `claudeBin` to an absolute path in `config.json` |+| "does not understand the flags Browsentic uses to sandbox a run" | Claude Code is too old | Update Claude Code |+| `EXTENSION_OFFLINE` | Browser closed, or not paired | Open the browser; `browsentic-mcp sessions` to check pairing |+| `TAB_UNREACHABLE` on a normal site | The extension needs reloading | ↻ at `chrome://extensions`; ordinary sites otherwise self-heal |+| `RUN_IN_PROGRESS` | One instruction at a time | Cancel the running one in the side panel |+| An action ran but nothing appears in `logs` | It matched the local intent grammar and never reached the daemon | Expected — those carry a ⚡ on the timeline. `yarn intent:check "<what you said>"` explains the routing. |++Useful commands:++```sh+browsentic-mcp status # daemon and extension state+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 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 stop+```++The daemon log lives at `~/.browsentic/daemon.log`.++---++## Development setup++```sh+yarn dev # build, launch a throwaway Chrome profile, hot reload+yarn dev:firefox+yarn build # production build+yarn zip # store-ready archive+yarn compile # type check the extension+yarn compile:mcp # type check the daemon+yarn mcp:dev # rebuild the daemon on change+yarn mcp:manifest # print the tool manifest, no browser needed+yarn intent:check # route a fixture table of utterances through the local grammar+yarn security:check+```++Before opening a pull request, run `yarn compile`, `yarn compile:mcp`, `yarn intent:check`,+`yarn security:check` and `yarn mcp:manifest`.++See [architecture.md](architecture.md) for how the pieces fit together, and+[features.md](features.md) for what they do.