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(settings): the settings page, the theme in config.json, both edited from the Mac app too, and a run that cannot loosen its own rules
Shahriard44e5bf60b4a
diff --git a/docs/guide/approvals.md b/docs/guide/approvals.mdindex 29834a3..58702fe 100644--- a/docs/guide/approvals.md+++ b/docs/guide/approvals.md@@ -171,13 +171,19 @@ gate stops being information.----## The Settings tab+## The settings page-Everything below is editable from **Settings** in the side panel, without opening a file.+Everything below is editable without opening a file, from two places that edit the same rows:++- **The extension's settings page** — the sliders button in the side panel's header or the popup,+ or right-click the toolbar icon → **Options** — under **Guardrails**.+- **The Mac app's Settings tab**, in its **Guardrails** card.++A change made in one shows up in the other at once, and so does a hand edit of the file.The screen is a list of **overrides**, not a list of switches that turn protection on. Every rowstarts off, meaning "use the default Browsentic ships" — so a fresh install has an empty settings-tab and the posture you get is the posture described here, whether or not you ever open it.+page and the posture you get is the posture described here, whether or not you ever open it.Turning a row on reveals **Allow / Ask / Block** and writes that one line to`~/.browsentic/config.json`. Turning it back off removes the line rather than writing a value equal@@ -194,6 +200,9 @@ accident. Hand-editing config.json still works if you genuinely mean it.Credential sealing appears in the list with no switch at all, because there is nothing to turn off:it is what keeps a plaintext password off the socket in the first place.+An agent run cannot use either screen's route to loosen its own rules: the daemon refuses a+settings change from a connection that has acted for a run, with `BLOCKED`.+---## Secrets are sealed before you are askeddiff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex 937ba17..bb6a9b6 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -3,7 +3,8 @@Everything is optional. Browsentic works with no config file at all.Settings live in `~/.browsentic/config.json`. The daemon re-reads it before every run, so an edit-applies to the next thing you ask — no restart.+applies to the next thing you ask — no restart. It also watches the file, so the extension's settings+page and the Mac app show a hand edit the moment you save it.`BROWSENTIC_HOME` relocates the whole state directory if you need it somewhere other than`~/.browsentic`. See [internals/state.md](../internals/state.md) for the full disk layout.@@ -22,6 +23,7 @@ Nothing here is required; this shows every key in one place.},"requireApproval": ["page.submitForm"],"maxConcurrentRuns": 3,+ "theme": "midnight","guardrails": {"rules": { "raw-html-read": "allow" },"unattended": "deny",@@ -70,9 +72,9 @@ Eight tab sessions may be *open* at once regardless; that ceiling is compiled in## Approvals and guardrails-Most of this section has a UI: the side panel's **Settings** tab writes these same keys, one row at-a time. Rows start off — meaning "use the default" — so an install that never opens the tab has no-`guardrails` key at all. Turning a row back off deletes its line rather than writing the default,+Most of this section has a UI: the extension's settings page and the Mac app's Settings tab both write+these same keys, one row at a time. Rows start off — meaning "use the default" — so an install that+never opens either has no `guardrails` key at all. Turning a row back off deletes its line rather than writing the default,which is why a hand-edited file and a panel-edited file look the same.| Key | Default | Notes |@@ -114,12 +116,19 @@ ceiling is clamped; a value that is not a number ≥ 1 falls back to the default## Appearance-The panel's theme is not in this file. It is a row of tiles in the side panel's **Settings** tab —-**Ember** (warm near-black, cyan), **Midnight** (cool blue-black, violet), **Phosphor** (a green-CRT) and **Daylight** (ink on paper) — and one click repaints the panel and the popup together.-Each tile is drawn in the theme it offers, so the preview is the thing itself.+| Key | Default | Notes |+| --- | --- | --- |+| `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**+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.-The choice is stored in the browser, never sent to the daemon, and needs nothing paired to work.+One theme serves every paired browser: picking one anywhere repaints the panel, the popup and the+settings page in all of them. A browser that has never been paired keeps its choice to itself and+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.---diff --git a/docs/guide/mac-app.md b/docs/guide/mac-app.mdindex fef5367..4ebfa68 100644--- a/docs/guide/mac-app.md+++ b/docs/guide/mac-app.md@@ -69,7 +69,7 @@ The tabs float at the top; ⌘1–⌘7 switch between them.| **Skills** | Every [skill](features/skills.md) the router can see and which folder it came from || **Activity** | Your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured || **Logs** | `~/.browsentic/daemon.log`, followed live |-| **Settings** | Light, dark or system appearance; whether the daemon starts with the app; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall |+| **Settings** | Light, dark or system appearance for this window; whether the daemon starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall |There is also a menu bar item with the daemon’s state and the same on, off and restart.diff --git a/docs/internals/extension.md b/docs/internals/extension.mdindex 753c56e..6cecefd 100644--- a/docs/internals/extension.md+++ b/docs/internals/extension.md@@ -81,10 +81,10 @@ it is the documented escape hatch.## The panel's tabs-`PanelNav` owns the tab strip: **Chat**, **History**, **Skills**, **Recordings**, **Schedules**,-**Settings**.-Adding one is a variant in `PanelTab`, an entry in `TABS`, and a branch in the side panel's body —-there is no router.+`PanelNav` owns the tab strip: **Chat**, **History**, **Skills**, **Recordings**, **Schedules**.+Adding one is an entry in `PANEL_TABS` (which `PanelTab` is derived from), an entry in `TABS` and+`RAIL_TABS`, and a branch in the side panel's body — there is no router. A stored tab that is no+longer in `PANEL_TABS` — `settings`, from before it moved out — opens on Chat.**The strip labels as much as it can afford.** A `ResizeObserver` measures the width the labelledrow actually needs and steps through three fits: every label, then only the open tab's, then icons@@ -94,12 +94,34 @@ learned, which is what keeps the strip from flapping between two fits at one panpractice five labels want ~485 px and one wants ~225 px, so a side panel at its usual size lands onthe middle fit.-**Settings** is two halves with nothing in common. **Guardrails** lives on the daemon rather than in-extension storage, like the Schedules tab's tasks: it reads and writes `~/.browsentic/config.json`-through two bridge ops, `guardrails` and `setGuardrail`, which forward to the socket frames of the-same name. The extension holds no copy — every write returns the daemon's fresh view, which is what-the panel then renders, and the whole half is empty until the daemon is up. **Appearance** never-leaves the browser, which is why it sits above and renders whether or not anything is paired.+## The settings page++Settings are not a panel tab. They are the extension's options page, `entrypoints/options/`, which+WXT turns into `options_ui` with `open_in_tab` on both browsers — so it needs no permission, Chrome+lists it as **Options** on the toolbar icon's menu, and Firefox as **Preferences** in about:addons.+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+`~/.browsentic/config.json`:++- Two bridge ops, `preferences` and `setPreference`, forward to the socket frames of the same name.+ The answer, `preferencesInfo`, is also pushed on connect and after every change to the file,+ whoever made it, and lands in `DaemonState.preferences`. The guardrail section renders that, so a+ row flipped in the Mac app moves here without a reload.+- **The theme stays in `storage.local` too**, because every surface paints from it before any socket+ exists. `servePreferences()` in [preferences.ts](../../src/lib/bridge/preferences.ts) keeps the two in+ step:+ - A push writes the daemon's theme locally.+ - A local pick is sent up, unless it only echoes the push.+ - A pick made while the daemon could not be told sets `browsentic/theme.unsynced`, and wins at the+ next connect. So does a pick made before the browser was ever paired, when config.json names no+ theme yet.### Themesdiff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.mdindex 75597d0..bd7bcb7 100644--- a/docs/internals/guardrails.md+++ b/docs/internals/guardrails.md@@ -106,7 +106,9 @@ the consequential actions. `unattended: 'allow'` goes back to waiving them.### The settings screen`guardrailSettings()` in [settings.ts](../../src/daemon/guardrails/settings.ts) describes the policy to-the side panel's Settings tab. Everything it returns is derived from `DEFAULT_RULES` and the live+the two screens that edit it: the extension's settings page and the Mac app's Settings tab. Both reach+it through [preferences.ts](../../src/daemon/preferences.ts), over the extension socket and `/control`+respectively, and a change from either — or a hand edit — is pushed to the other. Everything it returns is derived from `DEFAULT_RULES` and the liveconfig, so a rule added to the policy appears in the screen with no second edit, and a rule whosetitle or reason changes says the new thing in both places.@@ -122,6 +124,10 @@ the key, so config.json only names real decisions and a changed default still re`settingWritable()` is the gate: unknown ids, locked rules and wrong-shaped values are refused atthe daemon, not just hidden in the UI.+**A run cannot loosen its own rules.** `/control` is also how an agent run's tool server reaches the+daemon, so a control connection that has carried a `runId` is refused `setPreference` with `BLOCKED`.+The Mac app and a plain MCP client never send one.+### Overriding```jsondiff --git a/docs/internals/state.md b/docs/internals/state.mdindex b765f7b..5b35236 100644--- a/docs/internals/state.md+++ b/docs/internals/state.md@@ -32,7 +32,7 @@ Nothing lives in the repository.| --- | --- | --- || `daemon.json` | Each daemon at startup | The control token dies with the daemon that minted it. Read it with `browsentic token` || `auth.json` | Pairing | Session keys are per browser profile, keyed by its install id, and survive restarts. Cleared by `browsentic revoke` |-| `config.json` | You, and the agent picker | Re-read before every run — no restart needed. [Reference](../guide/configuration.md) |+| `config.json` | You, the agent picker, and the settings page and Mac app for `theme` and `guardrails` | Re-read before every run — no restart needed — and watched, so a hand edit reaches every open settings screen. [Reference](../guide/configuration.md) || `approvals.json` | **Always on ‹host›** | One action + host per entry. Only short-circuits a `confirm` || `models.json` | The daemon, reading each agent CLI's model list | A cache: deleting it only means the lists are read again. A failed read keeps the last list that read cleanly || `schedules.json` | The Schedules tab, `browsentic tasks` | At most 25 tasks. The daemon re-reads it every minute, so an edit from the CLI lands without a restart. Transcripts stay in the extension: the last three runs of each task |@@ -69,7 +69,11 @@ 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`. So do **diagnostics buffers** (`browsentic/diagnostics`), monitors and+(`browsentic/speechService`) are kept in `storage.local`.++**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+yet, handed over at the next connect. So do **diagnostics buffers** (`browsentic/diagnostics`), monitors andtimers — none of what a page reported about itself outlives the browser that reported it.## Relocatingdiff --git a/docs/internals/transport.md b/docs/internals/transport.mdindex eebb542..c904085 100644--- a/docs/internals/transport.md+++ b/docs/internals/transport.md@@ -111,7 +111,7 @@ dialling — but it never deletes the stored key. Only pairing again or `disconn## Protocol version-Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **14**). A mismatch closes the socket+Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **21**). A mismatch closes the socketwith an explicit reason instead of letting two incompatible frame vocabularies talk past each other.---