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: 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.mdindex 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 itoffers, 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 chohands it to the daemon when it first connects; one picked while the daemon is unreachable is handedover 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 configurablediff --git a/docs/guide/features/conversations.md b/docs/guide/features/conversations.mdindex 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 minimreopen 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 closebutton 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.mdindex 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 otherChromium 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 backwith 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 failurethere is a dropped connection, not a missing service. And one written off can win it back — dictatediff --git a/docs/internals/extension.md b/docs/internals/extension.mdindex 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 **PreferencesThe 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 alife, and on a back/forward-cache restore it drops the cached rail and asks the background for thecurrent 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 thediff --git a/docs/internals/state.md b/docs/internals/state.mdindex 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 apage paints before any socket is up. `browsentic/theme.unsynced` marks a pick the daemon has not heard