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(readme): restructure around key capabilities, quick start and resources

Shahriar1899bae407c3
diff --git a/README.md b/README.md
index 38519f8..4705bc9 100644
--- a/README.md
+++ b/README.md
@@ -1,57 +1,23 @@
-# Browsentic
+![Browsentic](https://raw.githubusercontent.com/imshaikot/browsentic/website/public/og.png)
-> Reimagine browsing as agentic. Browsentic hands your real, logged-in browser to the AI agent you already run — instruct it by voice, by typing, or by showing it once — and it turns that into real actions on the tab in front of you: clicking, filling, reading, navigating.
+# Browsentic – Agentic Browsing in the Browser You Already Use
-![License](https://img.shields.io/badge/license-MIT-blue)
-![Chrome](https://img.shields.io/badge/Chrome-Manifest%20V3-4285F4)
-![Node](https://img.shields.io/badge/node-%3E%3D20-339933)
+Hand your real, logged-in browser to the AI agent you already run. Browsentic is a browser extension plus a small local daemon: say what you want and it drives the page, ask a question and it reads the page and answers. It runs on [Claude Code](https://claude.com/claude-code), [Codex](https://developers.openai.com/codex/cli) or [Antigravity](https://antigravity.google/docs/cli/install) — whichever you already have logged in — and doubles as an [MCP server](docs/guide/mcp-clients.md) so any MCP client can drive the same browser. No account, no API key, no cloud service.
-Browsentic is a browser extension plus a small local daemon. Say what you want and it drives the page. Ask a question and it reads the page and answers. Every action it takes shows up on a live timeline, and anything consequential waits for your approval first.
+## Key Capabilities
-It runs on **an agent CLI you already have logged in** — [Claude Code](https://claude.com/claude-code), [Codex](https://developers.openai.com/codex/cli) or [Antigravity](https://antigravity.google/docs/cli). Pick one in the popup and switch whenever you like. There is no API client in this repository and no API key to configure.
+- **Your Real Browser, Not a Headless One**: Drives the tab in front of you, in your own profile, with your own logins and sessions
+- **Bring Your Own Agent**: Runs on the agent CLI you already pay for and are already signed in to — switch between Claude Code, Codex and Antigravity with one click
+- **35 Page Capabilities**: Reading, clicking, typing, dragging, form submission, navigation, screenshots, captchas, theming and accessibility, and background progress monitoring
+- **Voice, Text, or Demonstration**: Dictate in the side panel, type anywhere, or record yourself doing a job once and later say "do it like last time"
+- **Teach It a Site Once**: Point it at a site and it explores and writes reusable notes, so every later session already knows its way around
+- **Instant Commands**: "Go back", "scroll to the top", "open github.com" run in the browser in milliseconds instead of becoming an agent round trip
+- **Guardrails, Not Vibes**: A declarative policy gates consequential actions, confines each run to the sites it is about, and marks every byte of page text as untrusted data
+- **Off By Default**: A fresh install contacts nothing until you redeem a one-time pairing code
-## Features
+## Quick Start
-- **Voice or text.** Hands free dictation in the side panel, press to talk in the popup, plain typing anywhere.
-- **Real page control.** 35 page capabilities covering reading, clicking, typing, dragging, form submission, navigation, screenshots, captcha handling, theming and accessibility, and background progress monitoring.
-- **Site maps.** Point Browsentic at a site and it explores it, then writes reusable notes so later sessions already know their way around. See [Site maps](#site-maps-teach-it-a-site-once).
-- **Recordings.** Do a repetitive job once yourself and Browsentic keeps it as ordered steps, so "do it like last time" repeats it. See [Recordings](#recordings-show-it-once-repeat-it-later).
-- **Instant commands.** "Go back", "scroll to the top", "open github.com" run in the browser in milliseconds instead of becoming an agent run.
-- **A conversation per tab.** Several tabs can work at once, each in its own conversation and each staying in its own tab. The side panel follows whichever tab is in front, a collapsible strip lists the ones running, and closing a tab ends its session and files the transcript in History.
-- **Bring your own agent.** The side panel runs on Claude Code, Codex or Antigravity — chosen from the status pill in the side panel or from the popup, either of which tells you which ones are installed and what a missing one needs.
-- **Works as an MCP server.** Claude Code or any other MCP client can drive your real, logged in browser through the same local daemon.
-- **Off by default.** A fresh install connects to nothing until you redeem a one time pairing code.
-
-## Documentation
-
-This README is the short version. The long ones live in [`docs/`](docs/):
-
-- [Installation](docs/installation.md) — prerequisites, setup, configuration, limitations, troubleshooting, and driving Browsentic from a non-Claude agent
-- [Features](docs/features.md) — every capability and when to reach for it
-- [Architecture](docs/architecture.md) — how an instruction becomes a click, end to end
-
-## How it works
-
-```
-You ──speak or type──> Extension ──local WebSocket──> Daemon ──spawns──> your agent CLI
- ▲ (claude │ codex │ agy)
- └──────────────── page actions ─────────────────────┘
-
-Any MCP client ──stdio──> browsentic-mcp ──> the same daemon ──> the same browser
-```
-
-The extension dials out to the daemon, because a Manifest V3 service worker cannot listen for
-connections. One daemon owns the browser link, so several MCP clients can share one browser.
-
-## Requirements
-
-- Chrome or another Chromium browser (Firefox builds work too)
-- Node.js 20 or newer
-- One agent CLI on your `PATH`, logged in: [Claude Code](https://claude.com/claude-code) (`claude`),
- [Codex](https://developers.openai.com/codex/cli) (`codex`) or
- [Antigravity](https://antigravity.google/docs/cli) (`agy`)
-
-## Quick start
+Clone and build both halves — the extension and the local daemon (requires [Node.js](https://nodejs.org) 20 or newer):
```sh
git clone https://github.com/imshaikot/browsentic.git
@@ -59,301 +25,67 @@ cd browsentic
node scripts/setup.mjs
```
-That installs and builds both halves — the extension and the daemon, which is a separate package
-with its own dependencies. It needs nothing on your `PATH` but Node; the pinned Yarn release comes
-from the repository. Once installed, `yarn setup` re-runs the same thing.
-
-Load the extension: open `chrome://extensions`, enable **Developer mode**, choose **Load unpacked**
-and select `dist/chrome-mv3`.
-
-Then put the daemon on your `PATH` and pair your browser:
-
-```sh
-yarn mcp:link # writes to the global npm prefix, so it stays a separate step
-browsentic-mcp pair # prints a single use code, valid for 10 minutes
-```
-
-Open the Browsentic popup, paste the code and press **Connect**. The daemon issues a long lived
-session key that survives browser and daemon restarts, and dies only when you revoke it.
-
-That is the whole setup. Open the side panel and start talking.
-
-## Usage
-
-Type or speak an instruction into the side panel. Replies stream back token by token, each page
-action appears on a timeline as it happens, and follow ups continue the same conversation, so
-"now click the second one" works.
-
-Actions that change something other people can see wait for an explicit **Allow** or **Deny** — or
-**Always on ‹host›**, which grants that one action on that one site and stops asking. Review them with
-`browsentic-mcp approvals`.
-Form submission is gated by default.
-
-## Site maps: teach it a site once
-
-An agent that has never seen your site spends its first minutes rediscovering it: where search
-lives, what a button is really called, why the list looks empty until you scroll. Site maps do
-that exploration once and keep the result.
-
-Press **Map this site** in the side panel’s **Skills** tab, or say:
-
-```
-@site-mapper map this site
-```
-
-Browsentic reads the site's own `robots.txt` and `sitemap.xml`, looks up public background on the
-domain, then walks the site for a few minutes, taking screenshots as it goes. The result is a set
-of notes scoped to that domain:
-
-```
-~/browsentic/skills/acme-com/
-├── SKILL.md landmarks, key pages, how they connect, quirks
-├── map.json the structured report behind it
-├── screenshots/ captures taken during the crawl
-├── evidence/ the robots.txt and sitemap it worked from
-└── pages/ longer per page notes, kept out of the prompt
-```
-
-From then on, any instruction you give on that domain carries those notes. Elsewhere they are
-inert.
-
-**Nothing takes effect until you say so.** A map in flight is written to a staging directory the
-skill loader cannot read, so an unreviewed map is not merely unused, it is never opened. The panel
-shows you the exact markdown as plain text, never rendered, along with the domain it will match.
-**Activate** arms it, **Discard** deletes it.
-
-The crawl is read only and locked to one host. It cannot click, fill or submit, it cannot leave the
-site, and it is pinned to the tab it started in, so switching tabs stops it rather than following
-you. Size limits are enforced by the daemon, and config can narrow them but never widen them:
-
-| Setting | Default | Ceiling |
-| --- | --- | --- |
-| `maxPages` | 15 | 40 |
-| `maxScreenshots` | 10 | 24 |
-| `timeoutMs` | 600000 (10 min) | 1800000 (30 min) |
-
-Two switches change what a mapping run is allowed to do. `allowClicks` (off by default) lets it
-reach routes that only exist behind an interaction. `research` (on by default) lets it use web
-search for public background on the domain.
-
-> A map is written from pages an agent read, so read it before activating, as you would any
-> generated content. `research` is the one case where a run both reads pages and makes outbound
-> requests; turn it off to keep everything inside the browser.
-
-### Writing notes by hand
-
-If you would rather describe a site by hand, upload a markdown file from the side panel’s **Skills** tab:
-
-```markdown
----
-name: acme-admin
-description: Our internal admin tool.
-category: site-exploration
-domains: [admin.acme.com]
----
-
-Search is `#q` and submits on Enter, not on the button.
-Results lazy load. Click "Load more" until it disappears before counting anything.
-```
-
-Notes are overlays rather than replacements: on a matching site they are added on top of whatever
-Browsentic was already doing, so the normal driving and read only rules still apply. Prefix an
-instruction with `@acme-admin` to pin one regardless of where you are.
-
-Notes live outside the repository, are re-read on every run so an edit applies to the next thing
-you ask, and `browsentic-mcp skills` lists everything currently in scope.
-
-## Recordings: show it once, repeat it later
-
-A site map teaches Browsentic what a site **is**. A recording teaches it what **you do** there.
-
-Press **Record** in the side panel’s **Recordings** tab, then do the job yourself — click through the pages,
-fill the fields, submit the form — and press stop. Browsentic splits what you did into ordered
-steps, names them after what you accomplished, and keeps them in a list you can rename. Later,
-"do it like last time" runs them again. You can also just say it:
-
-```
-record my browsing session
-stop recording
-```
-
-A recording follows the tab it started in and nothing else. Navigations inside that tab become
-steps, other tabs are ignored, and closing the tab stops and saves. It runs for at most **15
-minutes**, warns you at 13, and stops itself at the limit.
-
-**What you type is not saved by default.** Every field you fill becomes a placeholder — `{{email}}`,
-`{{invoice_number}}` — and the assistant asks you for the value when it replays. Tick **Save what I
-type** if you would rather keep the literal values; passwords, hidden fields, one time codes and
-anything shaped like a card number are dropped either way.
-
-Replaying is not blind playback. The steps are a plan, not a script: the agent re-checks each target
-against the live page before acting, and prefers the visible text it recorded over the CSS selector,
-because selectors are what a redesign breaks first. Anything consequential still waits for your
-approval, even though you performed it yourself while recording. If a step no longer lands, the run
-stops and tells you which one, rather than improvising a different route to the same effect.
-
-Recordings live in the extension's own storage rather than on disk, so `browsentic-mcp skills` does
-not list them. The one time a recording leaves the browser is the local `claude -p` call that turns
-the raw trace into steps.
-
-## Instant commands
-
-Sending "go back" out to a language model costs a round trip and a few seconds to arrive at
-something the extension could do immediately. So every instruction is scored against a local
-grammar first. Confident single step commands run in the browser and stop there, marked with a
-bolt on the timeline. Everything else goes to the agent with the text untouched.
-
-| Runs locally | Goes to the agent |
-| --- | --- |
-| back, forward, reload | "is there a login button?" |
-| open github.com, open localhost:3000 | "open the settings menu" |
-| open github.com in a new tab | "close this tab", "switch to my gmail tab" |
-| google something, search the web for something | "search for wireless headphones" |
-| scroll up, down, top, bottom, page down | "scroll down and tell me what it says" |
-| press enter, hit escape, press arrow down | "click sign in and then fill in my email" |
-| click Sign in, tap Continue | "click Buy now", "click it" |
-| record my browsing session, stop recording | "record a video of this page" |
+Load the extension at `chrome://extensions` → **Developer mode** → **Load unpacked** → `dist/chrome-mv3`.
-The bias is toward escalating, because the two mistakes are not symmetric. Escalating something it
-could have handled costs a round trip. Acting on something it misread spends a wrong click on your
-real page. Questions, multi step asks, conditionals, vague targets and consequential clicks all go
-to the agent, as does any local command that runs and fails.
-
-## Use it from Claude Code
+Then put the CLI on your `PATH` and pair your browser:
```sh
-claude mcp add browsentic -- browsentic-mcp
+yarn mcp:link
+browsentic-mcp pair
```
-Claude Code now has 35 page tools plus `browsentic_status`, and three read only resources that
-return page context without spending a tool call. Tool definitions are generated from the same
-registry the extension ships, so they cannot drift from what the browser can actually do.
-
-## What it can do
-
-| Category | Capabilities |
-| --- | --- |
-| Read | Structured page snapshot with a layout diagram and stable selectors, rendered text or HTML, wait for an element to appear or vanish, screenshot the tab or one element |
-| Act | Click, hover, focus, type into inputs and contenteditables, stream text in keystroke by keystroke at a human pace, choose a `<select>` option, select text, press keys with modifiers, submit a form, drag one thing onto another — reordering a list, moving a card between columns, pulling a slider — and, for pages that only accept a genuine gesture, click or drag with a real browser-level mouse event |
-| Captchas | Identify the widget behind a "verify you are human" block, reading through the closed shadow roots and cross-origin frames vendors hide it in, and tick its checkbox with a real click. An image challenge is handed back to you to answer |
-| Move | Open a URL, back, forward, reload, scroll to an element or position, open a URL in a new tab, list and switch between open tabs, close one |
-| Files | List files stored in Browsentic and attach one to a file input on the page |
-| Recordings | List the browsing sessions the user recorded, and read one back as ordered, replayable steps |
-| Theme | Measure what the page is actually painting — background luminance, the palette by area, design tokens, a tree of coloured surfaces — score its text against WCAG contrast, then retheme it through the page's own dark/light hook and tokens, or through a filter when it has none, and revert |
-| Monitor | Find progress signals on a page, then watch one tab in the background until an upload, build or deploy completes — the tab is pinned, percent and ETA are tracked, the user is notified, and an MCP client can long-poll for completion |
+Paste the printed code into the Browsentic popup, press **Connect**, and open the side panel.
-Most capabilities take a target described by CSS selector, visible text, ARIA role or index.
-Targeting by visible text survives redesigns that break selectors.
+You also need one agent CLI on your `PATH` and logged in — `claude`, `codex` or `agy`. Full prerequisites in the [install guide](docs/guide/install.md).
-## Configuration
+## How It Works
-Optional, at `~/.browsentic/config.json`:
-
-```json
-{
- "agent": "claude",
- "agents": {
- "claude": { "bin": "/opt/homebrew/bin/claude", "model": "claude-sonnet-5" },
- "codex": { "bin": "codex" },
- "antigravity": { "bin": "agy" }
- },
- "requireApproval": ["page.submitForm"],
- "screenshotDir": "~/browsentic/screenshot",
- "skillsDir": "~/browsentic/skills",
- "siteMap": { "research": true, "allowClicks": false, "maxPages": 15 }
-}
```
+You ──speak or type──> Extension ──local WebSocket──> Daemon ──spawns──> your agent CLI
+ ▲ (claude │ codex │ agy)
+ └──────────────── page actions ─────────────────────┘
-`agent` is the CLI the side panel runs on, and the popup writes it for you — `agents.<name>.bin`
-is only needed when the daemon's `PATH` differs from your shell's. `requireApproval` lists the
-actions an agent run has to ask you about first. It defaults to form submission, which is the one effect that reaches someone other than you. Add any other action name
-to it — `"page.closeTab"` if you would rather approve each tab the agent closes, for instance. The
-cost of a longer list is a longer list: a prompt you see on every other tool call is a prompt you
-stop reading.
-
-Useful commands:
-
-```sh
-browsentic-mcp status # daemon, extension and agent state
-browsentic-mcp agent # which agents are installed, and which one runs the side panel
-browsentic-mcp agent codex # switch agents from the terminal
-browsentic-mcp sessions # which browsers are paired
-browsentic-mcp revoke # unpair everything, or one origin
-browsentic-mcp skills # every skill in scope, and where it came from
-browsentic-mcp logs # run starts, routed skills, every tool call
-browsentic-mcp restart # swap the running daemon for a fresh one
-browsentic-mcp stop
+Any MCP client ──stdio──> browsentic-mcp ──> the same daemon ──> the same browser
```
-There is no start command: the first CLI or MCP client that needs the daemon spawns it, and it
-lives until you stop it or it sits idle for 30 minutes with nothing attached.
+The extension dials out to the daemon, because a Manifest V3 service worker cannot listen for connections. One daemon owns the browser link, so several MCP clients can share one browser. Everything binds to `127.0.0.1`.
-## Privacy and security
+## Resources
-- **Nothing connects until you pair.** An unpaired extension never contacts the daemon.
-- **Two independent gates.** Any web page can open a WebSocket to loopback, so the daemon first
- classifies the peer by handshake `Origin`, which browsers set themselves and pages cannot forge,
- then requires proof of a pairing code or of a session key bound to that same origin. A web page
- can never reach the control path.
-- **Both ends prove themselves.** The daemon's ports are well known, so the extension does not
- trust whatever answers one: neither secret ever crosses the wire, and a peer that cannot prove it
- holds the same one is abandoned for the next port. That is what keeps another local process from
- posing as your daemon and driving your browser.
-- **Consequential actions ask first.** Approval prompts appear in the side panel with the action
- named. Cancelling a run stops it mid flight.
-- **Recordings capture what you do, not what you type.** A recording stores the identity of each
- field you fill and a placeholder for its value. Opting in to keeping literal values is per
- recording and off by default, and passwords, hidden fields, one time codes and card numbers are
- never stored either way. Recording only ever starts from your own click or your own words.
-- **Speech uses the browser's built in recognition.** Chrome's Web Speech API streams audio to
- Google to transcribe it. No model is bundled and nothing is downloaded. Replacing the speech
- engine is a one file change.
-- **State stays outside the repository.** Pairing keys, logs, config, skills and screenshots live
- under `~/.browsentic` and `~/browsentic`.
+- 📚 [Documentation](docs/)
+- 🚀 [Install and Pair](docs/guide/install.md)
+- ✨ [Features](docs/guide/features/)
+- 🧰 [All 35 Page Tools](docs/reference/tools.md)
+- 🔌 [Use It From Claude Code, Cursor or Zed](docs/guide/mcp-clients.md)
+- 🛡️ [Approvals and Guardrails](docs/guide/approvals.md)
+- 🏗️ [Architecture](docs/internals/)
+- 🩺 [Troubleshooting](docs/guide/troubleshooting.md)
-Two limits worth stating plainly. Pairing controls **which browser**, not which local process:
-anything running as your user can read the daemon lockfile and drive an already paired browser —
-though the token in it is minted fresh per daemon, so a copy stops working once that daemon exits.
-And an agent reading a hostile page is still susceptible to prompt injection, so treat page content
-as data, never as instructions.
+## Privacy and Security
-## Development
+- **Nothing Connects Until You Pair**: An unpaired extension never contacts the daemon
+- **Two Independent Gates**: The daemon classifies every peer by handshake `Origin` — which browsers set and pages cannot forge — then demands proof of a pairing code or an origin-bound session key. A web page can never reach the control path
+- **Both Ends Prove Themselves**: Neither secret crosses the wire; each side answers the other's nonce, so no local process can squat a port and pose as your daemon
+- **Consequential Actions Ask First**: Form submission, file upload, answering a captcha and leaving the run's sites all pause for an explicit Allow or Deny
+- **Agent Runs Are Contained**: The spawned CLI gets Browsentic's tools and nothing else — no shell, no filesystem, no other MCP servers, and a sealed environment stripped of your cloud keys and tokens
+- **Recordings Capture What You Do, Not What You Type**: Passwords, hidden fields, one-time codes and card numbers are never stored
-```sh
-yarn setup # install and build both projects from scratch
-yarn dev # build, launch a throwaway Chrome profile, hot reload
-yarn dev:firefox
-yarn build # production build
-yarn zip # store ready archive
-yarn check # everything a pull request needs: both type checks, both fixture suites
-yarn mcp:build # rebuild the daemon and MCP server
-yarn mcp:restart # rebuild, then swap the running daemon for the fresh build
-yarn mcp:manifest # print the tool manifest, no browser needed
-```
+Two limits worth stating plainly: pairing controls **which browser**, not which local process, and an agent reading a hostile page is still susceptible to prompt injection. Both are covered in [Limits](docs/guide/limits.md).
-Explain a single routing decision:
-
-```sh
-yarn check:intent "take me to the checkout page"
-```
+## Contributing
-Yarn 4 is the package manager and the release is pinned inside the repository, so whichever `yarn`
-is on your `PATH` re-executes into the right one. No global install or Corepack setup is needed.
+Found a bug 🐛 or have an idea for a capability ✨? Adding a page capability is one file plus one line in the registry, which publishes it as an MCP tool at the same time. See the [contributing guide](docs/internals/contributing.md) for the setup, the checks, and the four conventions that are load-bearing at runtime.
-Built with [WXT](https://wxt.dev), React 19, TypeScript, Tailwind CSS v4,
-[shadcn/ui](https://ui.shadcn.com) and [zod](https://zod.dev).
+## License
-## Contributing
+Browsentic is MIT licensed.
-Issues and pull requests are welcome. Adding a page capability is a single file plus one line in
-the registry, which publishes it as an MCP tool at the same time. Four conventions in an action
-module are load bearing at runtime rather than at compile time: touch `document`/`window` only
-inside `execute()`, keep underscores out of action names, `.describe()` every input field, and
-validate with `ActionError` inside `execute()` rather than zod `.refine()`/`.transform()`.
+- **Source Available**: Always visible source code
+- **Local First**: No cloud component, no telemetry, no account
+- **Extensible**: Add your own page capabilities, skills and agent runners
-Before opening a pull request, run `yarn check`. If you touched the action registry, also run
-`yarn mcp:manifest` and keep [docs/tools.md](docs/tools.md) in step with what it prints.
+## What does Browsentic mean?
-## License
+**Short answer:** "Browse" + "agentic".
-MIT
+**Long answer:** Most browser automation asks you to hand the work to a *different* browser — a headless one, in a container, logged in to nothing. Browsentic is the other way round: the agentic part happens in the browser you are already looking at, with the sessions you are already signed in to. The name is the thesis — browsing, made agentic, where you already browse.