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: the macOS app guide, its internals page, and the new CLI commands

Shahriar63182444183d
diff --git a/docs/guide/README.md b/docs/guide/README.md
index b849d6d..2c94981 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -7,7 +7,7 @@ Everything you need to run Browsentic on your own machine and your own browser.
Three short steps, about five minutes in total. There is no account, no API key and no cloud
service.
-1. **[Install](install.md)** — one command, then load the extension
+1. **[Install](install.md)** — one command, then load the extension. On a Mac, the [app](mac-app.md) does the same from a window
2. **[Pair](pair.md)** — connect your browser with a single-use code
3. **[First run](first-run.md)** — a tour of the side panel, and your first instruction
diff --git a/docs/guide/install.md b/docs/guide/install.md
index 06c5e2f..759b206 100644
--- a/docs/guide/install.md
+++ b/docs/guide/install.md
@@ -29,6 +29,9 @@ Two things worth knowing before you start:
## Install
+On macOS there is an app that does all of this from a window, Node included:
+[Browsentic for macOS](mac-app.md). Everywhere else, and on a Mac if you prefer a terminal:
+
```sh
npx browsentic setup
```
diff --git a/docs/guide/mac-app.md b/docs/guide/mac-app.md
new file mode 100644
index 0000000..c404e01
--- /dev/null
+++ b/docs/guide/mac-app.md
@@ -0,0 +1,95 @@
+# Browsentic for macOS
+
+A native app that installs Browsentic and runs it from a window. It is the same command and the
+same daemon as [`npx browsentic setup`](install.md) — the app carries them inside itself, lays them
+down in `~/.browsentic`, and then drives them, so nothing here needs a terminal.
+
+Requires macOS 14 or newer, on Apple silicon or Intel.
+
+---
+
+## Install
+
+1. Download `Browsentic-<version>.dmg` from the
+ [latest release](https://github.com/imshaikot/browsentic/releases/latest).
+2. Open it and drag **Browsentic** onto **Applications**.
+3. Open the app.
+
+The build is signed ad hoc and is not notarized. If macOS refuses to open it, right-click the app
+and choose **Open** once, or run `xattr -dr com.apple.quarantine /Applications/Browsentic.app`.
+
+## The first screen: what your Mac already has
+
+The app opens on six checks and runs them on its own:
+
+| Check | Passes when | If it does not |
+| --- | --- | --- |
+| **This Mac** | always | — |
+| **Node.js runtime** | `node` 20 or newer is on your `PATH` | **Install** downloads the current LTS from nodejs.org into `~/.browsentic/runtime/node`, verified against its published SHA-256. No Homebrew, no password |
+| **Browsentic command** | `~/.browsentic/cli` holds the version this app carries | **Install** copies it there and writes the `browsentic` launcher to `~/.browsentic/bin` |
+| **Browser extension** | the same version is unpacked at `~/browsentic/extension/chrome-mv3` | **Install** unpacks it |
+| **A Chromium browser** | Chrome, Brave, Edge, Arc, Vivaldi, Opera or Chromium is installed | **Get Chrome** opens the download page. Advisory — it does not block you |
+| **An AI agent** | `claude`, `codex` or `agy` is on your `PATH` | **Install Claude Code** runs `npm i -g @anthropic-ai/claude-code`. Advisory |
+
+**Set up everything** installs the first three in one click. A browser and an agent are yours to
+choose, so each has a button of its own. When everything required is in place the app moves on by
+itself; on later launches that takes about two seconds.
+
+> **Why the extension is not in `~/.browsentic`.** Chrome’s **Load unpacked** dialog is the
+> system folder picker, which hides dotfolders, and a browser’s pairing is tied to the extension’s
+> absolute path. So the extension lives in `~/browsentic/extension/chrome-mv3`, exactly where the
+> command puts it, and everything else goes in `~/.browsentic`.
+
+## The window
+
+The tabs float at the top; ⌘1–⌘7 switch between them.
+
+| Tab | What you do there |
+| --- | --- |
+| **Overview** | Turn the daemon on and off with the power button, restart it, see its address, version and whether the extension is connected and in sync. Copy the extension’s path, or open `chrome://extensions` in your browser with the path already on the clipboard |
+| **Browsers** | Get a [pairing code](pair.md) with a live countdown, see every paired browser, unpair one or all |
+| **Agents** | See which of Claude Code, Codex and Antigravity are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs |
+| **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 |
+
+There is also a menu bar item with the daemon’s state and the same on, off and restart.
+
+**Closing the window does not stop anything.** The daemon is a background process of its own, so
+the side panel and any MCP client keep working with the app closed or quit.
+
+## `browsentic` in your terminal
+
+**Settings → “browsentic” in your terminal** links the launcher into a folder that is already on
+your `PATH` and already writable — `~/.local/bin`, `/opt/homebrew/bin` or `/usr/local/bin`. No shell
+profile is edited and no password is asked for. After that every command in the
+[CLI reference](../reference/cli.md) works, against the same install the app manages.
+
+If you also have `npm i -g browsentic`, remove it (`npm rm -g browsentic`) so there is one command,
+not two that can drift apart.
+
+## Updating
+
+Settings shows a banner when a newer release is out. Download the new DMG, replace the app, open
+it: the first screen notices the command and the extension are older than the ones it carries,
+and **Set up everything** replaces both and restarts the daemon. Then press ↻ on the Browsentic card
+at `chrome://extensions`, which is the one step no installer can do for you.
+
+`browsentic update` does not replace an install the app made; it says so and points back here.
+
+## Uninstall
+
+**Settings → Uninstall…** runs [`browsentic uninstall`](../reference/cli.md#uninstall): it unpairs
+every browser, stops the daemon and removes `~/.browsentic` and `~/browsentic`, optionally keeping
+your skills. Remove the Browsentic card at `chrome://extensions` first, and drag the app to the
+Trash afterwards.
+
+## Building it yourself
+
+```sh
+yarn mac:dmg # → dist/mac/Browsentic.app and dist/mac/Browsentic-<version>.dmg
+```
+
+That needs the Swift toolchain — Xcode or the Command Line Tools. The source is a SwiftPM package
+in [`src/mac/`](../../src/mac); see [internals/mac-app.md](../internals/mac-app.md).
diff --git a/docs/internals/README.md b/docs/internals/README.md
index 5286def..96b98f7 100644
--- a/docs/internals/README.md
+++ b/docs/internals/README.md
@@ -22,6 +22,7 @@ Read in order, these pages follow a request through all of them:
| **8.** [Subsystems](subsystems.md) | Monitors, recordings, site maps, files, screenshots |
| **9.** [State on disk](state.md) | Every file Browsentic writes, and why it is where it is |
| **10.** [Contributing](contributing.md) | Build topology, the checks, and adding a capability |
+| **11.** [The macOS app](mac-app.md) | What is native, what stays in the daemon, and how the payload is laid down |
Looking for an error code? [reference/errors.md](../reference/errors.md).
diff --git a/docs/internals/mac-app.md b/docs/internals/mac-app.md
new file mode 100644
index 0000000..afd3be5
--- /dev/null
+++ b/docs/internals/mac-app.md
@@ -0,0 +1,65 @@
+# The macOS app
+
+`src/mac/` is a SwiftPM package with no dependencies and no Xcode project. It builds
+`Browsentic.app`, a SwiftUI control panel that **installs** the Node half of Browsentic and then
+**drives** it. It holds no intelligence and reimplements nothing: the daemon stays the daemon.
+
+## Why the daemon stays
+
+The daemon is where the extension socket, the handshake, the MCP server, the guardrails and the
+agent runners live, all of it in TypeScript shared with the extension through `src/lib/`. A native
+rewrite would fork the action registry and the wire protocol for no gain — the daemon idles at a
+few megabytes and the expensive thing it does is spawn an agent CLI. What *is* native is everything
+the app does continuously: it speaks the daemon’s `/control` WebSocket itself, so a status refresh
+is one frame on an open socket rather than a `node` process every two seconds.
+
+## Two ways in, by cost
+
+| Path | Used for | Where |
+| --- | --- | --- |
+| **The control socket** — `ws://127.0.0.1:<port>/control`, bearer token from `daemon.json` | `status`, `sessions`, `pair`, `revoke`, `agent` set and grant | [ControlClient.swift](../../src/mac/Sources/Browsentic/Core/ControlClient.swift), the same frames as [remote-bridge.ts](../../src/daemon/remote-bridge.ts) |
+| **The installed command** — `node ~/.browsentic/cli/dist/cli.js …` | `start`, `stop`, `restart`, `setup`, `uninstall`, and the `--json` listings for `agent`, `skills`, `approvals`, `downloads` | [CLI.swift](../../src/mac/Sources/Browsentic/Core/CLI.swift) |
+
+Anything that reads or writes disk goes through the command, so config overrides (`downloadDir`,
+`skillsDir`, `extensionDir`) are resolved in exactly one place. The open control socket is also
+what keeps the daemon from idling out while the app is up.
+
+A `ControlRequest` change in [control.ts](../../src/daemon/control.ts) needs the matching change in
+`ControlClient.swift` and `Models.swift`; nothing checks that for you.
+
+## The payload
+
+[build-app.sh](../../src/mac/Scripts/build-app.sh) stages `Contents/Resources/payload/` in the npm
+package’s layout — `dist/cli.js`, `dist/daemon-main.js`, `skills/`, `extension/chrome-mv3/`,
+`package.json` — because `cli.js` resolves `../skills` and `../extension` from where it sits. Like
+`stage-extension.mjs` it validates and never builds: a manifest version that disagrees with
+`src/daemon/package.json` is fatal.
+
+[Payload.swift](../../src/mac/Sources/Browsentic/Core/Payload.swift) copies that to
+`~/.browsentic/cli` with a directory swap and writes `.browsentic-app.json` beside it.
+`installKind()` in [npx.ts](../../src/daemon/npx.ts) reads that marker and answers `app`, which
+makes `upgradeCli()` step aside: an app install is only ever replaced by a newer app. The
+**extension** is still installed by `browsentic setup`, file by file, for the reasons
+[install.ts](../../src/daemon/install.ts) gives — and to the same path, for the reasons
+[paths.ts](../../src/daemon/paths.ts) gives.
+
+## PATH
+
+A GUI app inherits launchd’s `PATH`, which has neither Homebrew nor `~/.local/bin`. The daemon
+spawns the agent by name and inherits its environment from whoever started it, so
+[Shell.swift](../../src/mac/Sources/Browsentic/Core/Shell.swift) asks the user’s login shell for
+its `PATH` once and starts every child with that. Skip this and a daemon started from the app
+reports every agent as `AGENT_MISSING`.
+
+## Build and test
+
+```sh
+cd src/mac
+swift build && swift test # swift-testing, no XCTest
+ARCHS=arm64 Scripts/build-app.sh # quick local bundle; the default is a universal binary
+```
+
+CI builds and tests it on `macos-15`; the release workflow’s `mac` job attaches the DMG to the
+GitHub release after the npm publish. Colours in
+[Theme.swift](../../src/mac/Sources/Browsentic/Theme/Theme.swift) are Ember and Daylight from
+`globals.css`, converted from oklch — re-derive them when the extension’s palette changes.
diff --git a/docs/internals/state.md b/docs/internals/state.md
index 81d95cc..5a09229 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -11,7 +11,10 @@ Nothing lives in the repository.
├── config.json optional, hand-written
├── approvals.json 0600 "always on this site" grants, one action + host per entry
├── daemon.log run starts, routed skills, every tool call and its outcome
-└── skills/ hand-written skill overrides
+├── skills/ hand-written skill overrides
+├── cli/ macOS app only: the command, the daemon, bundled skills, the extension payload
+├── bin/ macOS app only: the `browsentic` and `browsentic-mcp` launchers
+└── runtime/node/ macOS app only, and only when the Mac had no Node 20+: a private copy from nodejs.org
~/browsentic/ (paths configurable)
├── extension/chrome-mv3/ the unpacked extension `browsentic setup` installs
@@ -27,6 +30,7 @@ Nothing lives in the repository.
| `auth.json` | Pairing | Session keys are per extension origin 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) |
| `approvals.json` | **Always on ‹host›** | One action + host per entry. Only short-circuits a `confirm` |
+| `cli/`, `bin/`, `runtime/` | [Browsentic.app](../guide/mac-app.md) | Replaced whole on every app update. `cli/.browsentic-app.json` is what makes `installKind()` answer `app`, which turns the npm self-update off |
| `daemon.log` | The daemon | `browsentic logs`. Local [instant commands](../guide/features/instant-commands.md) never appear here, by design |
## The one that is not yours
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index ea39af5..16b7cb9 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -73,6 +73,7 @@ See [guide/pair.md](../guide/pair.md).
| `browsentic agent` | Show which agent runs the side panel, and which are installed |
| `browsentic agent <name>` | Switch to `claude`, `codex` or `antigravity` |
| `browsentic agent fix <name>` | Let Browsentic fix what that agent still needs |
+| `browsentic agent model <name> [model]` | Pin that agent’s model in `config.json`; omit the model to go back to the CLI’s own default |
`agent fix antigravity` appends exactly one entry, `mcp(browsentic/*)`, to `permissions.allow` in
`~/.gemini/antigravity-cli/settings.json`. See [guide/agents.md](../guide/agents.md).
@@ -103,10 +104,14 @@ configurations written against the older name keep working.
| `browsentic downloads clear` | Delete all of them |
| `browsentic token` | The control token, for MCP clients. Not for the browser |
+`agent`, `skills`, `approvals` and `downloads` take `--json`. It is what the [macOS app](../guide/mac-app.md)
+reads, so the app and a terminal can never disagree about what is on disk.
+
## Lifecycle
| Command | Does |
| --- | --- |
+| `browsentic start` | Bring the background daemon up, if it is not already |
| `browsentic stop` | Stop the background daemon, whichever of 8765–8767 is answering |
| `browsentic restart` | Stop the daemon and bring up a fresh one |
| `browsentic --version` / `-v` | Print the version |
@@ -129,6 +134,8 @@ Not the CLI, but frequently wanted alongside it:
| `yarn daemon:restart` | Rebuild the daemon, then swap the running one for it |
| `yarn daemon:manifest` | Build and print the tool manifest |
| `yarn check` | Both type checks plus both fixture suites |
+| `yarn mac:app` | Build both halves, then `dist/mac/Browsentic.app` around them (macOS only) |
+| `yarn mac:dmg` | The same, wrapped in `dist/mac/Browsentic-<version>.dmg` |
| `yarn check:intent "<utterance>"` | Explain how one instruction would be routed |
Full list: [internals/contributing.md](../internals/contributing.md).