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: reaching Browsentic from the popup, the right-click menu and the keyboard, and the settings page's Extension section

Shahriare209fa2972fe
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 6038ccc..1da4df3 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -121,7 +121,7 @@ ceiling is clamped; a value that is not a number ≥ 1 falls back to the default
| --- | --- | --- |
| `theme` | absent (Ember) | `ember`, `midnight`, `phosphor` or `daylight` — the look of the side panel, the popup and the settings page |
-It is a row of tiles under **Appearance** on the extension's settings page, and under **Browser theme**
+It is a row of tiles under **Appearance** in the **Extension** section of the extension's settings page, and under **Browser theme**
in the Mac app's Settings tab — **Ember** (warm near-black, cyan), **Midnight** (cool blue-black,
violet), **Phosphor** (a green CRT) and **Daylight** (ink on paper). Each tile is drawn in the theme it
offers, so the preview is the thing itself.
@@ -131,6 +131,20 @@ settings page in all of them. A browser that has never been paired keeps its cho
hands it to the daemon when it first connects; one picked while the daemon is unreachable is handed
over at the next connect. The Mac app's own window keeps its separate System / Light / Dark setting.
+### The Extension section
+
+Below the theme, the same section holds what belongs to one browser alone. None of it is in
+`config.json`; each browser keeps its own.
+
+| Block | What it sets |
+| --- | --- |
+| **Right-click menu** | Whether a right-click on a page offers **Open Browsentic** (the side panel) and **Open Browsentic (Hands Free)**. Both are on until you switch one off. With both on, the browser gathers them under a **Browsentic** entry |
+| **Keyboard shortcuts** | Shows the keys for **Open the popup**, **Open or close the side panel** and **Start or stop hands-free**. The browser owns these: it gives the side panel **Alt+Shift+B** and hands-free **Alt+Shift+H** (**⌥⇧B**, **⌥⇧H** on a Mac) at install unless something else already has them, and **Change shortcuts** opens its own shortcuts page. Firefox has the popup and the sidebar only |
+| **Hands-free** | **Hold to talk** — the same switch as the mic's own menu |
+
+The hands-free item, shortcut and block show only in a browser that can transcribe speech — see
+[Hands-free → Which browsers](features/hands-free.md#which-browsers).
+
---
## Things that are not configurable
diff --git a/docs/guide/features/conversations.md b/docs/guide/features/conversations.md
index fdaa9d2..f885f59 100644
--- a/docs/guide/features/conversations.md
+++ b/docs/guide/features/conversations.md
@@ -60,9 +60,10 @@ how many runs are live, and its edge picks up the working colour. It stays minim
reopen it.
The rail is drawn into the page, so it cannot appear on pages Browsentic is not allowed into —
-`chrome://` pages, the Chrome Web Store and the new tab page. The toolbar icon and the right-click
-**Open Browsentic** item always work; while the panel is open, that item reads **Close Browsentic**
-and closes it instead.
+`chrome://` pages, the Chrome Web Store and the new tab page. The toolbar icon, the right-click
+**Open Browsentic** item and the **Open or close the side panel** shortcut (**Alt+Shift+B**,
+**⌥⇧B** on a Mac, unless something else already had it) always work; while the panel is open, the
+item reads **Close Browsentic** and the shortcut closes it instead.
The rail belongs to the minimized state alone. Closing the panel with the browser's own close
button removes any rail from every page — only the header's collapse button leaves one behind.
diff --git a/docs/guide/features/hands-free.md b/docs/guide/features/hands-free.md
index 884474c..2343327 100644
--- a/docs/guide/features/hands-free.md
+++ b/docs/guide/features/hands-free.md
@@ -5,22 +5,28 @@ and everything you would reach for in the panel is a hover away.
Hands-free exists only in browsers that can turn speech into text — Chrome, Edge, and the other
Chromium browsers with a speech service behind them. Anywhere else there is no detach button, no
-`/hands-free` and no mic on the page (see [Which browsers](#which-browsers)).
+`/hands-free`, no **Open hands-free** in the popup, no right-click item and no mic on the page (see
+[Which browsers](#which-browsers)).
---
## Turning it on
-Either of:
+Any of:
- the **detach** button in the side panel's header, just left of minimize
- typing **`/hands-free`** in the composer — the `/` menu offers it as soon as you type `/hand`, and
`/hand-free` works too
+- **Open hands-free** in the toolbar popup, beside **Open side panel**
+- **Open Browsentic (Hands Free)** when you right-click a page; while the mic is on, it reads
+ **Close Browsentic (Hands Free)** and takes it away
+- the **Start or stop hands-free** shortcut — **Alt+Shift+H** (**⌥⇧H** on a Mac) unless something
+ else already had it; see [Settings → Extension](../configuration.md#the-extension-section)
-The panel folds down into a mic and closes, and the same mic rises at the bottom middle of the page.
-It follows you from tab to tab. Opening the side panel again — from the mic's own menu, the toolbar
-icon or the right-click **Open Browsentic** item — turns hands-free off; the panel and the mic never
-listen at the same time.
+From the panel, it folds down into a mic and closes; from anywhere else the mic simply appears. It
+rises at the bottom middle of the page and follows you from tab to tab. Opening the side panel again
+— from the mic's own menu, the toolbar icon or the right-click **Open Browsentic** item — turns
+hands-free off; the panel and the mic never listen at the same time.
Hands-free lasts until you open the panel or the browser closes. A browser that restarts comes back
with the panel, never with a microphone already on.
@@ -109,7 +115,7 @@ Browsentic offers hands-free only where it can actually hear you:
| **Chrome, Edge** | Offered |
| **Firefox** | Never offered — it has no speech recognition, and no hidden page to listen from |
| **Brave** | Never offered — it ships the speech API with no service behind it, so every attempt fails |
-| **Other Chromium browsers** | Offered until their speech service first fails without ever having transcribed a word. From then on the detach button and `/hands-free` are gone, and a mic already on the page leaves with a note saying why |
+| **Other Chromium browsers** | Offered until their speech service first fails without ever having transcribed a word. From then on the detach button, `/hands-free`, the popup button and the right-click item are gone, and a mic already on the page leaves with a note saying why |
A browser whose speech service has transcribed even once keeps hands-free for good: a later failure
there is a dropped connection, not a missing service. And one written off can win it back — dictate
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index 6cecefd..dbe8ca2 100644
--- a/docs/internals/extension.md
+++ b/docs/internals/extension.md
@@ -102,12 +102,21 @@ lists it as **Options** on the toolbar icon's menu, and Firefox as **Preferences
The panel's header, the popup's header and the connection sheet open it with
`runtime.openOptionsPage()`, which focuses a settings tab already open rather than adding another.
-The page is a sidebar of four sections — **Appearance**, **Guardrails**, **Agent**, **Connection** —
-with the open one in the URL hash, so a reload or a link lands on it. **Agent** and **Connection** are
-the same `AgentPicker` and `DaemonLink` the popup and the connection sheet show; those keep theirs,
-so a blocked run is still one click from its fix.
-
-**Appearance and Guardrails are shared with the Mac app**, and the daemon keeps both in
+The page is a sidebar of four sections — **Extension**, **Guardrails**, **Agent**, **Connection** —
+with the open one in the URL hash, so a reload or a link lands on it; an unknown hash,
+such as the old `#appearance`, lands on **Extension**. **Agent** and **Connection** are the same
+`AgentPicker` and `DaemonLink` the popup and the connection sheet show; those keep theirs, so a
+blocked run is still one click from its fix.
+
+**Extension** is the theme, then what belongs to this browser alone, in `storage.local`: the
+right-click items (`browsentic/contextMenu`), the keyboard shortcuts, and hold to talk
+(`browsentic/pushToTalk`, the switch the orb's menu writes too). The shortcuts are the manifest's
+`commands`, declared from [shortcuts.ts](../../src/lib/settings/shortcuts.ts) with suggested keys; the
+page lists them with `commands.getAll()`, re-read whenever it comes back into view, because the
+browser owns the keys and only its own page changes them — `chrome://extensions/shortcuts`
+(`edge://` on Edge), or `commands.openShortcutSettings()` on Firefox.
+
+**The theme and Guardrails are shared with the Mac app**, and the daemon keeps both in
`~/.browsentic/config.json`:
- Two bridge ops, `preferences` and `setPreference`, forward to the socket frames of the same name.
@@ -202,9 +211,18 @@ own side of the same problem: on injection it removes any rail element left by a
life, and on a back/forward-cache restore it drops the cached rail and asks the background for the
current state with the rail channel's `sync` op.
-The same panel-presence signal drives the context menu: the item reads **Open Browsentic** or
-**Close Browsentic** to match, and a click on *Close* shuts the panel — Firefox's background closes
-the sidebar inside the gesture, Chromium panels are told over the run port to close themselves.
+The same panel-presence signal drives the context menu, which
+[launchers.ts](../../src/lib/bridge/launchers.ts) repaints from scratch — `removeAll`, then one
+`create` per item, one paint at a time — whenever the panel opens or closes, hands-free starts or
+ends, the settings page switches an item, or the speech service is found missing. **Open Browsentic**
+reads **Close Browsentic** while a panel is open, and a click on *Close* shuts it — Firefox's
+background closes the sidebar inside the gesture, Chromium panels are told over the run port to
+close themselves. **Open Browsentic (Hands Free)** exists only where `handsFreeSupported()` says
+speech works, reads **Close Browsentic (Hands Free)** while the orb is up, and toggles
+`browsentic/handsFree`, exactly as the panel's detach button and the popup's **Open hands-free** do.
+The `toggle-side-panel` and `toggle-hands-free` shortcuts go through the same two toggles; the panel
+opens before anything is awaited, because both a menu click and a shortcut hand over a gesture the
+first `await` would spend.
Pages that refuse content scripts — `chrome://`, the Web Store, the new-tab page — get no rail.
That is the same `TAB_UNREACHABLE` set as everywhere else, and it is why the toolbar icon and the
diff --git a/docs/internals/state.md b/docs/internals/state.md
index dcef3dc..95c1a98 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -69,7 +69,8 @@ state under `browsentic/dictation`, and the approvals it has already announced u
`browsentic/approvalsAnnounced`) — a restarted browser never comes back with a microphone on.
Only where the orb was dragged to (`browsentic/orbPosition`), whether hold-to-talk is on
(`browsentic/pushToTalk`) and whether this browser's speech service has ever worked
-(`browsentic/speechService`) are kept in `storage.local`.
+(`browsentic/speechService`) are kept in `storage.local`, along with which right-click items this
+browser shows (`browsentic/contextMenu`, both on when absent).
**The theme** is config.json's `theme`, mirrored into `storage.local` under `browsentic/theme` so a
page paints before any socket is up. `browsentic/theme.unsynced` marks a pick the daemon has not heard