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: Browsentic Home, the new tab page: a feature page, the internals (a side panel only a click opens, the frequent sites permissions, the off switch and Chrome’s Change back question), its storage key, the store kit’s permission rows and reviewer step, and troubleshooting rows

Shahriarfc78cd5ffe43
diff --git a/README.md b/README.md
index 1b414ff..de88b40 100644
--- a/README.md
+++ b/README.md
@@ -140,7 +140,7 @@ The extension dials out to Browsentic Bridge, because a Manifest V3 service work
![The side panel in Chrome partway through a run, waiting for approval to send a reminder; the Mac app's Overview and its one-click setup; the Windows app's agent picker and its Android phone checks](docs/assets/side-panel-and-apps.webp)
-The [side panel](docs/guide/features/conversations.md) is where you work with the agent. Every page action shows up as a step, and consequential ones, such as submitting a form, wait for your [approval](docs/guide/approvals.md).
+The [side panel](docs/guide/features/conversations.md) is where you work with the agent. Every page action shows up as a step, and consequential ones, such as submitting a form, wait for your [approval](docs/guide/approvals.md). A new tab opens [Browsentic Home](docs/guide/features/new-tab.md), a full-page composer with your frequent sites, which hands the task to the side panel as soon as you send it; you can switch it off.
The desktop apps for [macOS](docs/guide/mac-app.md) and [Windows](docs/guide/windows-app.md) ([experimental](docs/guide/limits.md#windows-is-experimental)) install Node and Browsentic Bridge in one click, turn the Bridge on and off, add the extension to each browser, pick the [agent CLI](docs/guide/agents.md) and its model, and check an [Android phone](docs/guide/features/android.md) before the side panel drives it.
diff --git a/docs/guide/features/README.md b/docs/guide/features/README.md
index bde2326..2da782b 100644
--- a/docs/guide/features/README.md
+++ b/docs/guide/features/README.md
@@ -10,6 +10,7 @@ If you have not set Browsentic up yet, start with [Install](../install.md), [Pai
| | |
| --- | --- |
| [Conversations](conversations.md) | Typing and dictating, one conversation per tab, the sessions strip, history |
+| [New tab](new-tab.md) | Browsentic Home on every new tab: a composer, your frequent sites and recent conversations, and how to switch it off |
| [Hands-free](hands-free.md) | Talking to the page through a mic you can drag anywhere, with the side panel put away |
| [Instant commands](instant-commands.md) | Commands such as "go back" and "scroll to the top" that run in milliseconds without an agent |
| [A-Eye](a-eye.md) | Pointing at an element instead of describing it, and the agent asking you to point |
diff --git a/docs/guide/features/new-tab.md b/docs/guide/features/new-tab.md
new file mode 100644
index 0000000..9002ab8
--- /dev/null
+++ b/docs/guide/features/new-tab.md
@@ -0,0 +1,76 @@
+# New tab
+
+Browsentic Home is the page a new tab opens on: a composer for a task, the sites you visit most, and
+your recent conversations. It is on until you switch it off.
+
+---
+
+## What it shows
+
+- **The composer**, the same one the side panel has: type a task, or `/` for skills and commands,
+ attach a file, or press the mic to dictate. The chip beside the send button names the agent CLI
+ and model the task goes to; press it to pick another.
+- **Suggestions** under an empty composer: tasks on the sites you visit most, such as listing the
+ pull requests waiting on your GitHub review. Pressing one puts it in the composer to edit. Nothing
+ is sent until you send it.
+- **Frequent sites**: up to eight, as the browser ranks them. Hover one and press **×** to hide it.
+- **Recent conversations**: runs going on in other tabs, with **Watch**, then your last four
+ conversations. **All conversations** opens the side panel's History.
+- **The header**: the connection pill (pairing and the agent picker), a button that opens the side
+ panel, and **Customize**, which holds the theme, the frequent sites switch, the switch for Home
+ itself and a link to every setting.
+
+## Sending a task
+
+Sending from Home opens the side panel in the same key press or click, with the conversation in it.
+When the agent takes the tab to a site, the site replaces Home and the side panel carries on with the
+same conversation, because a conversation belongs to its tab rather than to the page in it.
+
+Until then, Home shows the request and where it stands: the step the agent is on, an approval it is
+waiting for (with **Allow** and **Deny**), or the reply. A question that needs no site is answered
+on Home and in the side panel alike.
+
+Instant commands work here too. **go to github.com** opens the site straight away, with no agent.
+
+A recent conversation picks up where it was. One still open in another tab switches you to that tab;
+one from history continues in this tab, which goes to the page the conversation was on.
+
+## Switching it off
+
+Turn off **Open Browsentic Home on new tabs** under **Settings → Extension → New tab**, or
+**Browsentic Home** in the page's **Customize** menu. The same places switch the frequent sites off,
+and bring back the sites you hid.
+
+A browser takes its new tab page from an extension's manifest, so Browsentic cannot give the page
+back while it is installed. With Home off, it hands each new tab on instead:
+
+- **Chrome** shows its own new tab page, at `chrome://new-tab-page/`.
+- **Edge, Brave, Firefox** and other browsers keep their own page out of an extension's reach, so
+ they show a plain page of your frequent sites, with a link to turn Home back on.
+
+### Chrome's "Change back to Google?" question
+
+The first time Chrome shows Browsentic Home, on Windows, Mac and ChromeOS, it asks whether to keep
+the new tab page. **Keep it** keeps Browsentic and Home. **Change back to Google** switches off all
+of Browsentic, the side panel included.
+
+To keep Browsentic and get Chrome's own new tab page back, choose **Keep it**, then switch Home off
+as above. If Browsentic was switched off already, turn it back on at `chrome://extensions`.
+
+Firefox shows a notice of its own the first time. Keep the change there too; with Home switched
+off, Firefox shows the plain page of frequent sites.
+
+## Where it stops
+
+- **A side panel that is already open stays open on Home.** Chrome can hide a side panel on one tab
+ only when the panel belongs to that tab, and Browsentic's follows you from tab to tab.
+- **The keyboard starts in the address bar**, as on any new tab page. Click the composer, or click
+ anywhere on the page and start typing.
+- **A message sent by voice**, after a pause rather than a key press, cannot open the side panel. Home
+ shows the run, and **Open the side panel** brings the panel up.
+- **The mic never starts on its own here**, even when it was left on in the side panel.
+- **Firefox** asks before Browsentic reads your most visited sites, the first time you press **Show
+ frequent sites**.
+- **Incognito and private windows** keep the browser's own new tab page.
+- **A Chromium browser with no side panel** has the toolbar button's launcher follow the run
+ instead.
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 29e3242..ad0fd45 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -97,6 +97,9 @@ Those three answer most questions. The Bridge's log is at `~/.browsentic/daemon.
| --- | --- | --- |
| `TAB_UNREACHABLE` on a normal site | The extension needs reloading | Turn Browsentic off and on at `chrome://extensions` (press ↻ on an unpacked copy). Ordinary sites otherwise recover by themselves |
| `TAB_UNREACHABLE` on `chrome://`, the Web Store, the new-tab page | Those pages cannot host a content script | Go to an http(s) page with `page_navigate`, which still works on these pages |
+| New tabs open Browsentic instead of the browser's own page | That is [Browsentic Home](features/new-tab.md) | Switch it off under **Settings → Extension → New tab**, or in Home's **Customize** menu. Chrome then shows its own new tab page; other browsers show a plain page of your frequent sites |
+| Browsentic is gone after Chrome asked "Change back to Google?" | Chrome's **Change back** switches off the whole extension, not only its new tab page | Turn Browsentic back on at `chrome://extensions`. To get Chrome's own new tab page, switch Home off in **Settings → Extension → New tab** instead |
+| Sent a task from a new tab, and no side panel opened | The panel opens with the key press or click that sends. A message sent by voice after a pause has neither, and some Chromium browsers have no side panel | Press **Open the side panel** on the page, or click Browsentic in the toolbar |
| `TARGET_NOT_FOUND` for something clearly on screen | The page changed since the snapshot, or the element is inside a captcha widget's shadow root | Take a new snapshot with `page_getPageInfo`. For a captcha, use [`page_solveCaptcha`](features/captcha.md) |
| A captcha keeps setting new image challenges | The vendor distrusts the browser, however well each round is answered; this is common with automated or headless browsers | Solve one round yourself in the page; a person's answer usually clears the distrust. See [Captchas](features/captcha.md#image-challenges) |
| `DEBUGGER_UNAVAILABLE` | DevTools is open on that tab | Close DevTools, or use `page_clickElement` instead of `page_trustedClick` |
@@ -154,6 +157,8 @@ These apply only when another tool drives Browsentic through its optional MCP en
| A theme change vanished | Themes do not survive a reload or a navigation. Reapply it |
| A site map was written but nothing changed | Maps are staged for review. Open **Skills** in the panel and press **Activate** |
| The panel switched conversations on its own | The panel follows the tab in front, and each tab has its own conversation |
+| The side panel stays open beside Browsentic Home | Chrome can hide a side panel on one tab only when the panel belongs to that tab, and Browsentic's follows you across tabs |
+| Typing on a new tab goes into the address bar | Browsers keep the keyboard in the address bar on a new tab page. Click Home's composer, or click the page and type |
| A recording's typed values came back as `{{placeholders}}` | That is the default. Tick **Save what I type** to keep literal values |
---
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index cb874fd..c117545 100644
--- a/docs/internals/extension.md
+++ b/docs/internals/extension.md
@@ -57,9 +57,10 @@ a `browser_specific_settings.gecko` block the Chrome build has no use for:
behind whichever agent CLI the user runs.
- **`strict_min_version: 140.0`**: the first Firefox that understands the data-collection key.
-Four permissions are filtered out of that build (`sidePanel`, `debugger`, `offscreen` and
-`userScripts`): the Firefox Manifest V2 build has no use for any of them, and AMO's validator flags
-each name it does not know. The Firefox sidebar is `sidebar_action`, which WXT derives from the same
+Six permissions are filtered out of that build (`sidePanel`, `debugger`, `offscreen`,
+`userScripts`, `topSites` and `favicon`): the Firefox Manifest V2 build has no use for most of them,
+and AMO's validator flags each name it does not know. `topSites` comes back as an optional
+permission, which Browsentic Home asks for (see [Browsentic Home](#browsentic-home-the-new-tab-page)). The Firefox sidebar is `sidebar_action`, which WXT derives from the same
entrypoint, and the nine tools that need the debugger are left off the list a Firefox build offers
(see [Background vs content script](#background-vs-content-script)).
@@ -78,8 +79,8 @@ the content script via `browser.scripting.executeScript` and:
not leave a browser full of unreachable tabs.
Pages that refuse content scripts entirely (`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_UNREACHABLE` permanently. `page_navigate` still works there: on any tab that is not an http(s)
+page it goes straight through the tabs API, which is why it is the documented escape hatch.
---
@@ -130,7 +131,8 @@ such as the old `#appearance`, lands on **Extension**. **Agent** and **Connectio
`AgentPicker` and `DaemonLink` the connection sheet and the launcher show; those keep their copies,
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
+**Extension** is the theme, then what belongs to this browser alone, in `storage.local`: the new
+tab page (`browsentic/newTab`, see [Browsentic Home](#browsentic-home-the-new-tab-page)), 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
@@ -210,6 +212,58 @@ React mounts, and lets storage correct it a moment later. `index.html` carries
unpainted; `applyTheme` clears that inline colour, since an inline colour outranks every rule and
would otherwise pin `<html>` to a dark ground under a light theme.
+## Browsentic Home: the new tab page
+
+`entrypoints/newtab/` is the browser's new tab page; WXT writes it as `chrome_url_overrides.newtab`
+in both builds. It is a full-tab surface over the panel's own pieces: the `Composer` at
+`size="hero"` (no A-Eye, since there is no page to point at, and no scheduling, since the Schedules
+tab lives in the panel), an agent chip that opens `AgentPicker`, the status pill over `DaemonLink`
+and `AgentPicker`, frequent sites, and recent conversations. See [New tab](../guide/features/new-tab.md)
+for what the user sees.
+
+**Its conversation is its own tab's.** `useOwnTab()` reads the page's tab with `tabs.getCurrent()`,
+and `useRun(own)` pins the run port to that tab instead of following the tab in front, so a Home tab
+in the background still shows, and sends to, its own session. The browser hides a new tab page's
+address from the extension, so a run from Home starts with no URL, and with no URL the run's host
+scope starts open, as it does on a blank tab.
+
+**Sending opens the side panel first.** `sidePanel.open()` needs a live gesture, a click stays live
+for about five seconds, and a run reaches its first navigation well after that. So Home opens the
+panel in the key press or click that sends, then posts `instruct`. When the agent navigates the tab,
+the panel is already showing that tab's conversation, which the navigation does not touch: the
+session belongs to the tab. Two things were checked against Chrome 153 before settling on this:
+`open()` refuses outside a gesture, and `setOptions({ tabId, enabled: false })` removes only a
+tab-specific panel, so the window-wide panel cannot be hidden on Home alone and stays open there if
+it already was.
+
+**`navigate` leaves a page that is not a web page through the tabs API.** `routeInTab` sends it
+straight to `tabs.update` when the tab's URL is not http(s), without messaging the page first. An
+extension page in a tab receives `tabs.sendMessage` as soon as it has a `runtime.onMessage`
+listener, and its `undefined` answer would read as a navigation that happened.
+
+**Frequent sites** come from `topSites.get()`, one per host, minus the hosts the user hid, eight at
+most ([frequent-sites.ts](../../src/lib/home/frequent-sites.ts)). Chrome serves their icons through
+the `_favicon` endpoint (`favicon` permission); Firefox returns data URLs. In Chrome, `<all_urls>`
+already covers the warnings for `topSites` and `favicon`, so adding them did not hold the update for
+re-approval. Firefox would show `topSites` as a new warning and hold the update until it was
+accepted, so the Firefox build lists it under `optional_permissions`, and Home asks for it from a
+**Show frequent sites** click. The suggestions under an idle composer are tasks matched to those
+hosts in [suggestions.ts](../../src/lib/home/suggestions.ts), padded with general ones to three.
+
+**Switching Home off cannot give the slot back**: only the manifest overrides the new tab page. The
+page hands the tab on instead, through `tabs.update`, since a page may not open a `chrome://` address
+itself: Google Chrome goes to `chrome://new-tab-page/`, and every other browser, whose own page is out
+of an extension's reach, gets a plain page of frequent sites. The switch is `browsentic/newTab` in
+`storage.local`, mirrored to `localStorage` as `browsentic/newTab.paint` so a tab with Home off never
+paints it before handing on.
+
+**Home's mic is per page.** The panel's voice switch is a stored preference; Home's starts off on
+every tab, so a new tab never starts listening because the panel was left listening.
+
+**Chrome asks once whether to keep the new tab page**, on Windows, Mac and ChromeOS. Its **Change
+back** disables the whole extension (`DISABLE_USER_ACTION`), not only the page, and **Keep it** is
+remembered for good. The guide tells users to keep it and switch Home off in settings instead.
+
## Minimizing: the rail lives in the page
**Nothing can resize a side panel.** `chrome.sidePanel` offers `open`, `close`, `setOptions` and
diff --git a/docs/internals/state.md b/docs/internals/state.md
index d67d5f7..e4d3f92 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -91,6 +91,12 @@ are never logged or stored. See [Android phones](android.md).
**Blocked sites** are `browsentic/blockedSites` in `storage.local`: a list of up to 500 patterns that
the daemon never receives. Removing the extension removes it; each browser keeps its own.
+**Browsentic Home** is `browsentic/newTab` in `storage.local`: whether new tabs open Home and whether
+it shows frequent sites (both on when absent), and up to 100 hosts the user hid from that row. The
+on or off is mirrored to the extension's `localStorage` as `browsentic/newTab.paint`. The frequent
+sites themselves are read from the browser each time a new tab opens; they are never stored, and
+never sent to the Bridge.
+
**The star request** is `browsentic/starNudge` in `storage.local`: whether its star was clicked, the
conversations it asked in (three at most), and up to two conversation ids counted since the last
ask. It never leaves the browser.
diff --git a/docs/internals/stores.md b/docs/internals/stores.md
index 5ba0b6d..0ca8c03 100644
--- a/docs/internals/stores.md
+++ b/docs/internals/stores.md
@@ -75,6 +75,7 @@ WHAT IT DOES
• A Profile for the details forms keep asking for, plus standing instructions applied to every task
• Attach a file and ask about it alongside the page
• Runs several tasks in several tabs at once
+• A new tab page to start from: type a task, open a frequent site, or pick up a recent conversation. You can switch it off in settings
SAFETY AND PRIVACY
• Connects to nothing until you pair it with a one-time code
@@ -110,8 +111,9 @@ and reuses the same screenshots. The images (five 1280×800 screenshots, a 440×
**Single purpose**
> Browsentic is a browser harness for the AI agent the user already runs on their own computer. From
-> the browser's side panel, the user describes a task in words or by voice, and that agent carries it
-> out in their own tabs (reading pages, filling in forms, clicking through flows).
+> the browser's side panel, or from its new tab page, the user describes a task in words or by voice,
+> and that agent carries it out in their own tabs (reading pages, filling in forms, clicking through
+> flows).
**Permission justifications**
@@ -130,6 +132,8 @@ and reuses the same screenshots. The images (five 1280×800 screenshots, a 440×
| `debugger` | Used where a page's own scripts would otherwise block an action: trusted clicks and key presses, working inside cross-origin frames, and pages whose Content Security Policy blocks injected scripts. It attaches only to the tab a task is working on, and Chrome shows its standard banner while attached. |
| `offscreen` | Hands-free mode listens for the user's voice through an offscreen document, so it keeps working after the side panel is closed. |
| `userScripts` | Runs a saved tool that the user has reviewed and approved on each visit to its site. It works only after the user turns on Allow User Scripts for Browsentic. |
+| `topSites` | Shows the user's most visited sites on Browsentic's new tab page, as the browser's own new tab page does. The list stays in the browser; it is never sent anywhere. |
+| `favicon` | Shows each site's icon beside its name on the new tab page, from the browser's own icon cache. |
| Host permission `<all_urls>` | Browsentic works on whatever site the user is on, so it needs to read and act on any page the user asks it to. It does nothing on a page until the user gives it a task there, apart from features the user turns on themselves (a page monitor, a recording, or a saved tool set to run on every visit). |
The `commands` key (keyboard shortcuts) needs no justification.
@@ -157,5 +161,6 @@ Browsentic needs Browsentic Bridge on the computer and an AI agent CLI; the exte
2. Install and sign in to an agent CLI, such as Claude Code or Codex.
3. The app, or setup, shows a pairing code. Click Browsentic in the toolbar and enter it. (Skip any steps for loading an unpacked copy: the extension is already installed from the store.)
4. Open the side panel on any web page and type a task, for example: Summarise what this page says.
+5. Open a new tab: it shows Browsentic Home. Type: go to example.com. The side panel opens with the conversation and the tab goes to the site. Settings > Extension > New tab switches Home off.
Demo videos of the full flow: https://browsentic.com/demos/
```