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.
CLI reference
Every command and flag of browsentic, the command for Browsentic Bridge (the part of Browsentic
that runs on your computer).
browsentic <command>
With no command it prints usage. Most commands start the Bridge if it is not already running;
status, browsers, stop, logs, token, tools, skills, approvals, downloads and
uninstall do not.
Installing
| Command | Does |
|---|---|
browsentic setup |
Start the Bridge, then add the extension to a browser and pair the two |
browsentic update |
Pull the newest Bridge, restart it, and refresh the unpacked folder if you load one |
browsentic browsers |
List the browsers on this computer, where each gets the extension, and which are connected |
browsentic uninstall |
Stop the Bridge and remove everything Browsentic wrote |
On a terminal, setup checks your agent and asks which browser should get the extension. It opens
that browser's store page in it (the Chrome Web Store for Chrome, Edge, Brave, Arc, Vivaldi, Opera
and Chromium; the signed add-on for Firefox), prints a pairing code, and waits
up to five minutes for the browser to connect. Ctrl-C stops the wait and undoes nothing. With no
terminal and no --browser, it asks nothing: it prints where each browser gets the extension and a
code, so a script or an app never hangs on it.
Every run also registers the Bridge with each browser it finds, so the browser can start it when it
is down (wake-up: in status).
| Flag | Does |
|---|---|
--browser <name> |
chrome, edge, brave, arc, vivaldi, opera, chromium or firefox: skip the question. For Firefox it also says when Mozilla has not attached the signed add-on to this version's release yet |
--unpacked |
Write the extension to ~/browsentic/extension/chrome-mv3 and print the steps to load it at the browser's extensions page, for a browser that cannot reach a store or for an unreleased build |
--dir <path> |
With --unpacked, write it somewhere else. Needed for Flatpak or Snap browsers, which cannot read ~/browsentic without a filesystem grant. Remembered, so update refreshes the same copy |
--no-open |
Print the store link instead of opening it |
--no-wait |
Print the code and return, instead of waiting for the browser |
--no-pair |
Mint no code. update passes it |
--force |
Rewrite every file of the unpacked folder even when it already matches |
--no-self-update |
Run what this copy carries, without asking the registry whether a newer one exists |
--json |
Machine-readable result, with every browser's row, as the apps read it. Never asks, never waits |
The unpacked folder is written only when you ask for it, and kept current once it exists: setup
and update refresh it in place. Its path deliberately never carries a version. Chrome derives an
unpacked extension's ID from the absolute path of its directory, and the browser keeps the
extension's storage (including the install id and the session key) under that ID, so a versioned
path would unpair the browser on every update.
setup and update both replace the command itself when the registry has something newer. A
stale command runs a stale Bridge, lays down a stale unpacked folder, and reports "already
current". Under npx a stale copy lasts as long as the cache does, which is what made update look
like it did nothing; npx browsentic@latest checks every time. A pinned npx browsentic@<version>
is never upgraded, and a source checkout is told rather than touched.
Uninstall
| Flag | Does |
|---|---|
--dry-run |
Print the plan and stop |
--yes / -y |
Skip the confirmation. Required when stdin is not a terminal |
--keep-skills |
Leave skills/ behind. Site maps and hand-written notes have no other copy |
It removes the Bridge (found by probing 8765–8767, so an orphan whose lockfile was deleted is still
caught), ~/.browsentic, ~/browsentic, and every ~/.npm/_npx/* directory holding a copy of the
package. It lists, but does not touch, the extension in each browser, the command itself, your MCP
client's entry, and any directory you moved with screenshotDir, downloadDir or skillsDir.
See guide/install.md and guide/maintenance.md.
Pairing
| Command | Does |
|---|---|
browsentic pair |
Issue a one-time code to paste into the side panel (status pill → Connection → Pair with a code instead). 8 characters, valid 10 minutes, single use |
browsentic pairing [auto|ask|code] |
Show or set how a browser pairs through the native host: by itself (auto, the default), once you allow it (ask), or only with a code (code) |
browsentic requests |
The browsers waiting for you to allow them, in ask mode. --json for scripts |
browsentic approve [id] |
Allow a waiting browser (the only one, when there is one), or let a revoked or denied one back in by its id. --name <name> names it; --watch asks about each browser as it asks, until Ctrl-C |
browsentic deny <id> |
Turn a waiting browser down. It stays out until someone presses Reconnect in it and you allow it |
browsentic sessions |
List paired browsers, how each paired, and the ones kept out |
browsentic rename <id> <name> |
Name a paired browser, as the app's list shows it. An empty name clears it |
browsentic revoke [id] |
Unpair one browser by the id sessions prints, or all of them, and keep them from pairing again by themselves. An origin still works, and unpairs every browser presenting it |
See guide/pair.md.
Agents
| Command | Does |
|---|---|
browsentic agent |
Show which agent runs the side panel, and which are installed |
browsentic agent <name> |
Switch to claude, codex, antigravity, vibe, grok, cursor, qwen, opencode or deepseek |
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.
agent fix was called agent setup before setup came to mean installing Browsentic. The old
spelling still works and is undocumented.
Android
| Command | Does |
|---|---|
browsentic android |
Whether a phone is ready to drive from the side panel: adb, the phone, USB debugging, Chrome, Chrome open and the screen, one row each. A row that fails says what to do; when nothing is ready, the setup steps follow |
browsentic android open [url] |
Open Chrome on the phone, at that page if one is given (in a new tab when Chrome is already open). With more than one phone, name it with --serial <serial> |
android takes --json: the state the apps read, with the setup steps as guide. Where the
Bridge looks for adb, and the keys that name one or stop it using adb at all, are under
Android in the configuration guide. A Bridge still running
from before Android (protocol 22 or older) is not asked: both commands exit at once and say to
run browsentic restart.
MCP
| Command | Does |
|---|---|
browsentic mcp |
Serve MCP over stdio. What an MCP client runs, not something you type |
browsentic-mcp is a legacy alias binary that serves MCP on bare invocation, so client
configurations written against the older name keep working.
State and diagnostics
| Command | Does |
|---|---|
browsentic status |
The Bridge, which browsers can start it, the agent, Android, and one row per paired browser with its extension version, its store and whether it is connected; flags an unpacked copy that needs ↻ and two copies answering in one browser. The Android line says what the Bridge already knows and never starts adb: not checked until a browser is watching for phones |
browsentic logs |
Print the Bridge's log (~/.browsentic/daemon.log) |
browsentic tools |
Print the bundled tool manifest as JSON. No browser needed |
browsentic skills |
Every skill the router can see, tagged bundled, user or uploaded |
browsentic approvals |
The "always on this site" grants |
browsentic approvals clear [host] |
Forget them, all or one site's |
browsentic tasks |
Scheduled tasks, when each runs next and how it last went |
browsentic tasks pause|resume [id] |
Pause or resume one task, or every task at once. An id prefix is enough |
browsentic tasks delete <id> |
Delete a task |
browsentic downloads |
Files captured from pages, with notes and where they landed |
browsentic downloads clear |
Delete all of them |
browsentic token |
The control token, for MCP clients. Not for the browser |
agent, android, skills, approvals, tasks and downloads take --json. It is what the macOS and
Windows apps read, so an app and a terminal can never disagree about what is on disk.
Lifecycle
| Command | Does |
|---|---|
browsentic start |
Bring the Bridge up in the background, if it is not already |
browsentic stop |
Stop the Bridge, whichever of 8765–8767 is answering. A paired browser leaves it stopped until browsentic start, or an MCP client, starts it |
browsentic restart |
Stop the Bridge and bring up a fresh one |
browsentic --version / -v |
Print the version |
browsentic help / --help / -h |
Usage |
A rebuild does not replace a running Bridge. It keeps the old code in memory until stop or
restart. In the repository, yarn daemon:restart chains the rebuild with the restart.
Repository scripts
Scripts for a source checkout, not part of the CLI:
| Command | Does |
|---|---|
yarn setup |
Install and build both halves |
yarn daemon:link |
Put browsentic on your PATH from a source checkout |
yarn daemon:unlink |
Take it off again |
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 win:app |
Build both halves, then the Windows app's installer around them (Windows, or macOS with cargo-xwin) |
yarn win:preview |
The Windows app's window in a browser, against a stand-in daemon |
yarn check:intent "<utterance>" |
Explain how one instruction would be routed |
Full list: internals/contributing.md.