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.

10.4 KB
Raw Blame

State on disk

Where Browsentic keeps its state: ~/.browsentic and ~/browsentic on disk, npm's npx cache, and the browser's own storage for what never reaches disk. Nothing is kept in the repository.

Who writes what, where it lands, and the three things that never reach disk

~/.browsentic/                 (mode 0700, override with BROWSENTIC_HOME)
├── daemon.json    0600        lockfile: pid, port, control token, protocol + daemon version
├── auth.json      0600        outstanding pairing codes, session keys per browser, allowed and blocked browsers
├── config.json                optional, hand-written
├── profile.json   0600        the settings page's Profile: your details and standing instructions
├── approvals.json 0600        "always on this site" grants, one action + host per entry
├── models.json    0600        each agent CLI's own model list, as last read
├── schedules.json 0600        scheduled tasks and the last twenty runs of each
├── native-host/               the helper a browser launches to start the daemon and pair
├── stopped                    only after `browsentic stop`: the helper leaves the daemon down
├── daemon.start.lock          only while a daemon is being started: the one starter others wait for
├── daemon.log                 run starts, routed skills, every tool call and its outcome
├── skills/                    hand-written skill overrides
├── cli/                       desktop apps only: the command, the daemon, bundled skills, the extension payload
├── bin/                       desktop apps only: the `browsentic` and `browsentic-mcp` launchers (.exe on Windows)
└── runtime/node/              desktop apps only, and only when the computer had no Node 20+: a private copy from nodejs.org

~/browsentic/                  (paths configurable)
├── extension/chrome-mv3/      the unpacked extension `browsentic setup --unpacked` writes, when asked for
├── skills/                    panel uploads + activated site maps
│   ├── acme-com/SKILL.md
│   └── .staging/              maps awaiting review (unreadable to the loader)
└── screenshot/    0600        captures taken with save: true
File Written by Notes
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, each with how it paired (pairedBy) and any name given to it. approved lists the browsers allowed in ask mode; blocked the ones revoked or denied, which do not pair again by themselves (the newest 200 kept). Grants are never written here: they live in the daemon's memory for two minutes. browsentic revoke deletes a session and blocks it
config.json You, the agent picker, and the settings page and desktop 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
profile.json The settings page's Profile section Only exists while something is filled in: clearing every field deletes it. Re-read before every run and watched like config.json; kept apart from it so the config never holds personal details. Reference
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
native-host/ browsentic setup A launcher that runs this CLI with the PATH setup saw and Node's warnings off, since a host must write nothing to stderr. Each browser gets a manifest where it reads one (a registry key on Windows) naming the extension origins allowed to use it: both store listings always, the unpacked folder, and each paired browser. Chrome's and Mozilla's locations are written whether or not those browsers are installed, because Brave, Opera and other forks read Chrome's. The Bridge rewrites them on every start and every hour, only where something changed and never half-written, and repins a launcher whose Node or CLI has gone. A Bridge whose state lives outside the home folder registers nothing. On Windows, setup also registers the Browsentic\Bridge scheduled task Firefox's host starts the Bridge through. browsentic uninstall, and the Windows app's uninstaller, remove all of it
stopped browsentic stop and restart While it exists the helper starts no daemon, so a paired browser cannot undo a stop. The next daemon to start removes it
cli/, bin/, runtime/ The macOS or Windows app 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 never appear here, by design

npm's npx cache

~/.npm/_npx/<hash>/ belongs to npm, but a machine set up with npx browsentic setup keeps the whole package there (CLI and extension payload both), and npm reuses it without re-checking the registry. So it behaves like state: it decides which version you run, it survives deleting both directories above, and it is why a reinstall could land on a months-old build. browsentic update replaces it; browsentic uninstall deletes it.

State kept in the browser

Held secrets never reach disk. A credential the sanitizer seals out of a page is kept in the extension's browser.storage.session under browsentic/secrets, capped at 64 entries, expiring after two hours and emptied by the browser on restart. The daemon never receives one.

Recordings stay in the extension's own storage, not on disk. Removing the extension removes them.

Saved tools keep their code in the extension's storage.local under browsentic/savedTools; the daemon gets only a markdown note. A tool set to run on every visit is also registered with Chrome as a user script, rebuilt from that list whenever it changes, so removing a tool removes both.

Attached files stay there too: the bytes under browsentic:file:<id>, and the index under browsentic:files, where each entry records the conversation it belongs to, the file analyst's report and the agent session that report was handed to. A conversation's files are deleted when it leaves history. The daemon holds a copy only while the analyst reads it, in the agent's task workspace at 0600, and deletes it when the report is in.

Tab sessions live in browser.storage.session under browsentic/tabSessions, so they are gone when the browser closes. Diagnostics buffers (browsentic/diagnostics), monitors and timers are kept the same way: nothing a page reported about itself outlives the browser that reported it. So is hands-free mode (browsentic/handsFree, the listening state under browsentic/dictation, and the approvals it has already announced under 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, along with which right-click items this browser shows (browsentic/contextMenu, both on when absent) and whether agent actions are ringed on the page (browsentic/actionCues, off when absent).

The phone session is browsentic/phone in storage.session: the phone's serial, the phone tab's id and window, the phone's tabs and which one is in front, and why it ended. A conversation on the phone tab is a tab session like any other, marked phone: { serial }. Both go when the browser closes. Nothing about the phone reaches the Bridge's disk beyond daemon.log lines naming its serial, its Chrome version and each DevTools method sent, never its parameters; screencast frames are never logged or stored. See Android phones.

Pairing by itself keeps three values: browsentic/pairManual in storage.local while the user has pressed Disconnect (only Connect clears it), browsentic/pairLast in storage.local with what the last attempt found and when, which spaces the next one, and browsentic/staleKey in storage.session once the Bridge has said it holds no session for the stored key. The key itself stays until a new one replaces it.

Notices the app showed are browsentic/noticeTabs in storage.session: each notice's id and the tab a click brings back, the newest 30, gone with the browser.

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.

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.

Relocating

BROWSENTIC_HOME moves ~/.browsentic wholesale. screenshotDir and skillsDir in config move those two ~/browsentic subdirectories independently, and browsentic setup --unpacked --dir installs the extension somewhere else.


Next

Contributing →