Skip to content
Back to search

FSB

DOM-first AI browser automation for Chrome and MCP clients.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/fullselfbrowsing/FSB with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/fullselfbrowsing/FSB'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fullselfbrowsing--fsb/badge.svg)](/listings/fullselfbrowsing--fsb)

HTML

<a href="/listings/fullselfbrowsing--fsb"><img src="/api/listings/fullselfbrowsing--fsb/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**FSB shines when your AI client drives it directly.** Install the MCP server for your client of choice — one command, no manual config edits, and **no FSB API key needed** (your MCP client's model handles the reasoning):

| Client | One-command install | |--------|---------------------| | Claude Code | `npx -y fsb-mcp-server@latest install --claude-code` | | Claude Desktop | `npx -y fsb-mcp-server@latest install --claude-desktop` | | Cursor | `npx -y fsb-mcp-server@latest install --cursor` | | VS Code | `npx -y fsb-mcp-server@latest install --vscode` | | Windsurf | `npx -y fsb-mcp-server@latest install --windsurf` | | Codex | `npx -y fsb-mcp-server@latest install --codex` | | All at once | `npx -y fsb-mcp-server@latest install --all` |

Preview before writing: append `--dry-run`. Sanity check with `npx -y fsb-mcp-server@latest doctor`. Restart the client so the new MCP server appears.

**Then install the browser side** (the MCP bridge talks to the extension):

1. Get **FSB** from the [Chrome Web Store](https://chromewebstore.google.com/detail/badgafnfchcihdfnjneklogedcdkmjfk). 2. From your MCP client, try: `Search for cats on Google` or `Read this page and summarize it`.

Want to run FSB standalone from the extension popup/side panel? Open settings, paste an API key (xAI, Gemini, OpenAI, Anthropic, OpenRouter, LM Studio, or custom), and start there — no MCP needed.

**On OpenClaw?** Install FSB directly from [ClawHub](https://clawhub.ai/lakshmanturlapati/full-selfbrowsing). That is the fastest onboarding route. If you need the manual fallback, the FSB skill in [`skills/fsb/`](./skills/fsb/SKILL.md) still prints the canonical OpenClaw stdio config block and runs the doctor flow. The bare `--openclaw` install flag stays manual because OpenClaw's MCP config schema is unstable across builds.

**On Hermes?** Use the same skill at [`skills/fsb/`](./skills/fsb/SKILL.md). Run `node skills/fsb/scripts/print-hermes-yaml.mjs` to print the canonical `~/.hermes/config.yaml` `mcp_servers.fsb` block, or run `node skills/fsb/scripts/install-host.mjs` to detect a local Hermes config and gate the install on consent.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 697 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # FSB v0.9.95 Full Self Browsing
  2. <div align="center">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="extension/assets/fsb_logo_dark.png" />
  5. <source media="(prefers-color-scheme: light)" srcset="extension/assets/fsb_logo_light.png" />
  6. <img src="extension/assets/fsb_logo_light.png" alt="FSB Full Self Browsing" width="200" />
  7. </picture>
  8. ![FSB](https://img.shields.io/badge/FSB-Full_Self_Browsing-000000?style=for-the-badge)
  9. ![Version](https://img.shields.io/badge/version-0.9.95-0078D4?style=for-the-badge)
  10. ![Manifest V3](https://img.shields.io/badge/Manifest_V3-Chrome-34A853?style=for-the-badge&logo=googlechrome&logoColor=white)
  11. ![License](https://img.shields.io/badge/license-MIT-F5C518?style=for-the-badge)
  12. [![Online-Mind2Web](https://img.shields.io/badge/Online--Mind2Web-92.3%25-FF6B35?style=for-the-badge)](#benchmark)
  13. ![Stars](https://img.shields.io/github/stars/fullselfbrowsing/FSB?style=flat-square&logo=github&label=Stars)
  14. ![Forks](https://img.shields.io/github/forks/fullselfbrowsing/FSB?style=flat-square&logo=github&label=Forks)
  15. ![Issues](https://img.shields.io/github/issues/fullselfbrowsing/FSB?style=flat-square&logo=github&label=Issues)
  16. ![Last Commit](https://img.shields.io/github/last-commit/fullselfbrowsing/FSB?style=flat-square&logo=github&label=Last%20Commit)
  17. **AI-powered browser automation through natural language. Tell it what to do, and watch it browse for you.**
  18. *Pure structural intelligence. Zero vision. Zero guessing.*
  19. [Benchmark](#benchmark) · [What's New](#whats-new) · [Quick Start](#quick-start) · [MCP Server](#mcp-server) · [Architecture](#architecture) · [Providers](#ai-providers) · [Development](#development)
  20. </div>
  21. ---
  22. ## Benchmark
  23. <picture>
  24. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/online-mind2web-dark.svg" />
  25. <source media="(prefers-color-scheme: light)" srcset="docs/assets/online-mind2web-light.svg" />
  26. <img src="docs/assets/online-mind2web-light.svg" alt="Online-Mind2Web, top 10 agents by average success rate: Hark 97.7%, Navigator (n1.5) 97.3%, ACT-2 92.7%, FSB 92.3% (AI-reviewed result, 277/300), Navigator (n1-preview) 78.7%, Google Computer Use 69.0%, Operator 61.3%, ACT-1 (Aug 2025) 57.3%, Claude Computer Use 56.3%, ACT-1 (Jul 2025) 45.7%." />
  27. </picture>
  28. Average success rates on [Online-Mind2Web](https://huggingface.co/spaces/osunlp/Online_Mind2Web_Leaderboard), with FSB included.
  29. <details>
  30. <summary>Top 10 agents as a table</summary>
  31. | # | Agent | Average success rate |
  32. | ---: | --- | ---: |
  33. | 01 | Hark | 97.7% |
  34. | 02 | Navigator (n1.5) | 97.3% |
  35. | 03 | ACT-2 | 92.7% |
  36. | **04** | **FSB** | **92.3%** |
  37. | 05 | Navigator (n1-preview) | 78.7% |
  38. | 06 | Google Computer Use | 69.0% |
  39. | 07 | Operator | 61.3% |
  40. | 08 | ACT-1 (Aug 2025) | 57.3% |
  41. | 09 | Claude Computer Use | 56.3% |
  42. | 10 | ACT-1 (Jul 2025) | 45.7% |
  43. </details>
  44. FSB: [AI-reviewed result (277/300)](https://github.com/fullselfbrowsing/FSB/blob/mind2web/mind2web/BENCHMARK-REPORT.md).
  45. ---
  46. ## Overview
  47. FSB (Full Self Browsing) is an open source Chrome extension for AI powered browser automation. Describe a task in plain English; FSB reads the live DOM, builds a plan, executes browser actions, verifies results, and reports progress through the popup, side panel, or MCP.
  48. > FSB v0.9.95 is functional and production ready for supervised automation. Browser automation can still behave unpredictably on complex or sensitive sites, so monitor actions and test on non critical pages first.
  49. ### Why DOM First
  50. Project Mariner, Claude Computer Use, and OpenAI Operator rely heavily on visual page understanding. FSB uses page structure directly.
  51. | Metric | Vision based agents | FSB |
  52. |--------|---------------------|-----|
  53. | Page understanding | Screenshots | DOM, selectors, ARIA, forms |
  54. | Hidden elements | Often invisible | Available in structure |
  55. | Typical per step latency | 1 to 3 seconds | 50 to 200 ms |
  56. | Token/cost profile | Image heavy | Text/structure heavy |
  57. ### Quick Start TL;DR
  58. **FSB shines when your AI client drives it directly.** Install the MCP server for your client of choice — one command, no manual config edits, and **no FSB API key needed** (your MCP client's model handles the reasoning):
  59. | Client | One-command install |
  60. |--------|---------------------|
  61. | Claude Code | `npx -y fsb-mcp-server@latest install --claude-code` |
  62. | Claude Desktop | `npx -y fsb-mcp-server@latest install --claude-desktop` |
  63. | Cursor | `npx -y fsb-mcp-server@latest install --cursor` |
  64. | VS Code | `npx -y fsb-mcp-server@latest install --vscode` |
  65. | Antigravity | `npx -y fsb-mcp-server@latest install --antigravity` |
  66. | Codex | `npx -y fsb-mcp-server@latest install --codex` |
  67. | Cline | `npx -y fsb-mcp-server@latest install --cline` |
  68. | All at once | `npx -y fsb-mcp-server@latest install --all` |
  69. Preview before writing: append `--dry-run`. Sanity check with `npx -y fsb-mcp-server@latest doctor`. Restart the client so the new MCP server appears.
  70. **Then install the browser side** (the MCP bridge talks to the extension):
  71. 1. Get **FSB** from the [Chrome Web Store](https://chromewebstore.google.com/detail/badgafnfchcihdfnjneklogedcdkmjfk).
  72. 2. From your MCP client, try: `Search for cats on Google` or `Read this page and summarize it`.
  73. Want to run FSB standalone from the extension popup/side panel? Open settings, paste an API key (xAI, Gemini, OpenAI, Anthropic, OpenRouter, LM Studio, or custom), and start there — no MCP needed.
  74. **On OpenClaw?** Install FSB directly from [ClawHub](https://clawhub.ai/lakshmanturlapati/full-selfbrowsing). That is the fastest onboarding route. If you need the manual fallback, the FSB skill in [`skills/fsb/`](./skills/fsb/SKILL.md) still prints the canonical OpenClaw stdio config block and runs the doctor flow. The bare `--openclaw` install flag stays manual because OpenClaw's MCP config schema is unstable across builds.
  75. **On Hermes?** Use the same skill at [`skills/fsb/`](./skills/fsb/SKILL.md). Run `node skills/fsb/scripts/print-hermes-yaml.mjs` to print the canonical `~/.hermes/config.yaml` `mcp_servers.fsb` block, or run `node skills/fsb/scripts/install-host.mjs` to detect a local Hermes config and gate the install on consent.
  76. **On Grok Bot?** The marketplace wrapper lives in [`plugins/grok-bot/`](./plugins/grok-bot/README.md), with a pinned npm MCP server and one FSB skill. It uses Chrome on Bot's own computer; see its setup and privacy disclosures. Marketplace listing is pending publisher review.
  77. ### What It Does
  78. - Runs natural language browser tasks from the popup or side panel.
  79. - Supports xAI, Gemini, OpenAI, Anthropic, OpenRouter, LM Studio, and custom OpenAI-compatible endpoints.
  80. - Discovers live provider model lists and falls back to bundled defaults.
  81. - Uses 57 shared definitions (53 browser tools plus 4 trigger tools) and 69 registered MCP tools for external clients.
  82. - Provides DOM snapshots, action verification, smart waiting, stuck detection, visual feedback, and session logs.
  83. - Searches a 128-app capability catalog and invokes verified signed, audited, denylist-gated first-party API capabilities through the MCP capability surface.
  84. - Uploads real local files to file inputs through the supervised `upload_file` tool with sensitive-path safeguards.
  85. - Maintains long term memory for past sites, workflows, selectors, and task outcomes.
  86. - Includes secure credential and payment vault flows for supervised autofill.
  87. - Exposes a local MCP server so Claude Code, Codex, Cursor, VS Code, Antigravity, Cline, and other MCP clients can drive the browser.
  88. Background agents were removed in v0.9.45rc1. When the extension updates, it deletes the saved agent definitions and alarms they left behind. For scheduled or recurring work, use [OpenClaw](https://github.com/openclaw/openclaw) or [Claude Routines](https://www.anthropic.com/claude/routines).
  89. ### Common Use Cases
  90. - **QA and regression checks**: repeat page flows, click through states, fill forms, and collect action logs.
  91. - **Research**: navigate pages, extract visible information, and summarize results without relying on screenshots.
  92. - **Data entry**: move through structured forms with validation, dropdowns, custom controls, and table inputs.
  93. - **Ecommerce**: compare product pages, inspect prices, monitor availability manually, and prepare carts under supervision.
  94. - **Finance and dashboards**: read charts, tables, and current page state when a human remains in control.
  95. - **Trigger watchers**: watch one page element for changes, threshold crossings, or availability while Chrome and the extension stay open.
  96. - **Developer workflows**: drive GitHub, issue trackers, documentation sites, coding platforms, and browser-based tools.
  97. - **Accessibility and DOM inspection**: expose structure, labels, selectors, forms, and hidden controls for debugging.
  98. FSB is most reliable when the task can be expressed as page structure and user actions. It is intentionally not a stealth browser, scraper farm, or unsupervised account operator.
  99. ### Feature Detail
  100. | Area | Current behavior |
  101. |------|------------------|
  102. | DOM analysis | Captures visible and structural page data, element refs, selectors, forms, ARIA labels, and DOM deltas. |
  103. | Action execution | Supports clicks, typing, keys, scrolling, navigation, tabs, spreadsheet ranges, coordinate tools, direct JavaScript, and real file uploads. |
  104. | Capability catalog | Searches the 128-app catalog and invokes verified signed, audited, denylist-gated T1/T1b first-party API capabilities through `search_capabilities` and `invoke_capability`. Catalog-tail hits remain learn-pending, discovery-pending, or guarded fail-closed until proven. Sensitive origins are flagged, while denylisted origins remain blocked. |
  105. | Verification | Checks post-action state, loading behavior, DOM stability, and stuck-action repetition. |
  106. | UI surfaces | Popup chat, persistent side panel, options/control panel, logs, analytics, memory, vault, and sync controls. |
  107. | Model support | Hosted providers, OpenRouter routing, LM Studio local models, custom endpoints, and live model discovery. |
  108. | Output rendering | Markdown, sanitized HTML, Mermaid diagrams, Chart.js charts, and task progress messages. |
  109. | Observability | Session history, action logs, token/cost accounting, diagnostics ring buffer, and MCP status probes. |
  110. | Security | Encrypted keys, vault unlock flows, redaction helpers, DOMPurify, capability signature/audit gates, origin denylisting, upload-path denylisting, and restricted-tab recovery messaging. |
  111. | Trigger watchers | MCP callers can arm one-element watches with blocking or detached reporting, plus status/list/stop companions. |
  112. | DOM live preview | PhantomStream-backed capture, renderer, protocol, media mirroring, and relay compatibility with FSB-owned pairing, task status, overlays, and remote-control ownership. |
  113. The core design goal is to keep the browser as the source of truth. The model receives structured page context, makes a tool decision, and the extension verifies what changed before moving to the next step.
  114. ---
  115. ## What's New
  116. **Native Capability Catalog: first-party API execution.** Beyond DOM automation, FSB can search a capability catalog covering 128 apps and invoke verified API capabilities with `search_capabilities` and `invoke_capability`. Verified capabilities run through a router that checks the origin, verifies the recipe signature, checks the denylist, serializes the action, and logs an audit record that never includes secrets. Capabilities that are not yet verified are clearly labeled instead of being presented as ready to use. Every origin is allowed by default unless it is on the denylist, and denylisted origins stay blocked. Sensitive origins are flagged in the interface and the audit trail, and reading data through network capture on a sensitive origin still asks for extra confirmation. The API integration model is inspired by **OpenTabs** (see [Acknowledgements](#acknowledgements)). Capability execution is fully supported and has been tested, including live browser testing. The automated test suite is green.
  117. **`upload_file`: real file input uploads.** MCP clients and FSB autopilot can now call `upload_file(selector, file_path, tab_id?)` to set an absolute local disk path on a real `<input type="file">` through CDP `DOM.setFileInputFiles`, including inputs hidden behind styled dropzones. Uploads pass through one shared background chokepoint with a sensitive-path denylist and audit logging that does not persist disk paths. `drop_file` remains for synthetic drag/drop cases and pure drag-only zones.
  118. **PhantomStream 0.2.1 media mirroring.** Dashboard DOM live preview now consumes the published PhantomStream media side channel in reference mode, so progressive `<video>` and `<audio>` nodes can mirror alongside DOM snapshots. Adaptive HLS/DASH discovery remains deferred because it would require a new `webRequest` permission; MCP tool schemas, pairing, auth, and dashboard ownership behavior are unchanged.
  119. **Engineering milestone 0.11.0 — Trigger Tool (reactive DOM monitoring).** MCP callers can arm a watch on one page element with `trigger` and manage it with `stop_trigger`, `get_trigger_status`, and `list_triggers`. Watches support `live-observe` and `refresh-poll` modes, threshold/delta/regex/compound conditions, blocking or detached reporting, and a configurable concurrency cap. See [Trigger Watchers](mcp/README.md#trigger-watchers) for the full contract.
  120. **Showcase and ecosystem pages.** [full-selfbrowsing.com](https://full-selfbrowsing.com) added pages for [Lattice](https://full-selfbrowsing.com/lattice) (capability runtime SDK), [PhantomStream](https://full-selfbrowsing.com/phantom-stream) (DOM-native browser mirroring), [Prometheus](https://full-selfbrowsing.com/prometheus) (the autonomous browser build behind FSB), and a community [Site Maps](https://full-selfbrowsing.com/sitemaps) hub, plus a live [stats](https://full-selfbrowsing.com/stats) page with an anonymized active-regions globe, a [legal](https://full-selfbrowsing.com/legal) posture page, and an interactive knowledge-graph viewer on [About](https://full-selfbrowsing.com/about).
  121. Full history is in [`CHANGELOG.md`](./CHANGELOG.md); the MCP package keeps its own log in [`mcp/CHANGELOG.md`](./mcp/CHANGELOG.md).
  122. ---
  123. ## Repository Layout
  124. | Path | Purpose |
  125. |------|---------|
  126. | [`extension/`](./extension/README.md) | Chrome extension package. Load this directory as an unpacked MV3 extension. |
  127. | [`mcp/`](./mcp/README.md) | npm package `fsb-mcp-server`, the local MCP bridge for external AI clients. |
  128. | [`skills/fsb/`](./skills/fsb/SKILL.md) | OpenClaw + Hermes skill: doctor + stdio/YAML printers + consent gated install for multiple hosts. |
  129. | [`showcase/`](./showcase/README.md) | Marketing and dashboard site for full-selfbrowsing.com. Angular 20 static prerender + Express relay. |
  130. | `showcase/server/` | Node/Express deploy backend for pairing, PhantomStream-compatible relay, auth, and dashboard data. |
  131. | `server-py/` | Legacy Python/FastAPI-style backend prototype retained for reference. |
  132. | `tests/` | Node tests for extension modules, MCP contracts, bridge behavior, and regression coverage. |
  133. | `scripts/` | Repo maintenance and validation scripts. |
  134. Top level deploy and validation files:
  135. - `package.json` - root commands for validation, tests, packaging, and showcase helpers.
  136. - `Dockerfile`, `fly.toml` - production deploy for the showcase server on fly.io.
  137. - `.github/workflows/ci.yml` - validates extension, MCP smoke tests, and showcase build.
  138. - `.github/workflows/deploy.yml` - deploys the production site on `main` pushes.
  139. ---
  140. ## Screenshots
  141. <table>
  142. <tr>
  143. <td width="50%" align="center">
  144. <img src="extension/assets/screenshots/demo-task-input.png" alt="FSB side panel on YouTube, user entering a task" width="100%" />
  145. <br/><sub><b>Task Input</b></sub>
  146. </td>
  147. <td width="50%" align="center">
  148. <img src="extension/assets/screenshots/demo-task-result.png" alt="FSB automating YouTube search, typing Sunflower" width="100%" />
  149. <br/><sub><b>Task Execution</b></sub>
  150. </td>
  151. </tr>
  152. </table>
  153. <details>
  154. <summary><strong>More screenshots</strong></summary>
  155. #### Dashboard and Analytics
  156. <img src="extension/assets/screenshots/dashboard-analytics.png" alt="Options dashboard showing token usage charts and cost breakdown by model" width="100%" />
  157. #### API Configuration
  158. <img src="extension/assets/screenshots/api-configuration.png" alt="API configuration panel with provider selection and key entry" width="100%" />
  159. #### Passwords Manager
  160. <img src="extension/assets/screenshots/passwords-manager.png" alt="Passwords manager for storing site credentials used during automation" width="100%" />
  161. #### Memory and Site Explorer
  162. <img src="extension/assets/screenshots/memory-site-explorer.png" alt="Memory viewer and site explorer showing crawled site structure" width="100%" />
  163. #### Intelligence Knowledge Graph
  164. <img src="extension/assets/screenshots/intelligence-graph.png" alt="3D knowledge graph visualizing site guide categories and supported domains" width="100%" />
  165. </details>
  166. ---
  167. ## Quick Start
  168. ### Prerequisites
  169. - Chromium 116+ in a supported stable desktop browser: Chrome, Edge, Brave, or Chromium.
  170. - One AI provider setup:
  171. - xAI API key: https://x.ai/api
  172. - Gemini API key: https://aistudio.google.com/app/apikey
  173. - OpenAI API key: https://platform.openai.com/api-keys
  174. - Anthropic API key: https://console.anthropic.com/account/keys
  175. - OpenRouter API key: https://openrouter.ai/keys
  176. - LM Studio local server running at `http://localhost:1234`
  177. - A custom OpenAI-compatible chat completions endpoint
  178. ### Install The Extension
  179. ```bash
  180. git clone https://github.com/fullselfbrowsing/FSB.git
  181. cd FSB
  182. ```
  183. 1. Open `chrome://extensions/`.
  184. 2. Enable **Developer mode**.
  185. 3. Click **Load unpacked**.
  186. 4. Select the `extension/` directory.
  187. 5. Click the FSB toolbar icon, open settings, configure a provider, and test the API connection.
  188. Start with simple tasks such as:
  189. - `Scroll down`
  190. - `Search for cats on Google`
  191. - `Click the first search result`
  192. - `Read this page and summarize it`
  193. Reload the extension from `chrome://extensions/` after local code changes. Reload open tabs after the extension reloads so content scripts re-inject.
  194. For an unpacked build, record the ID on `chrome://extensions/`. A different install path or profile can produce a different ID; if `doctor` reports `ORIGIN_PIN_MISMATCH`, run `npx -y fsb-mcp-server@latest pair --reset` and pair the new installation. One browser profile attaches to the local bridge at a time. `doctor` and `status` show the attached extension ID, version, install instance, connection time, and normal-window count. The MCP server and extension have independent versions. Branded Chrome 137 removed the `--load-extension` flag; use **Load unpacked** in Chrome, or use [Chrome for Testing or Chromium when a command-line flag is required](https://groups.google.com/a/chromium.org/g/chromium-extensions/c/1-g8EFx2BBY/m/S0ET5wPjCAAJ).
  195. ### First Run Checklist
  196. 1. Open the FSB control panel from the extension.
  197. 2. Select a provider and model.
  198. 3. Enter the matching API key or local endpoint.
  199. 4. Use **Test API** to confirm the model can answer.
  200. 5. Open a normal webpage, not a browser-internal page.
  201. 6. Try a read-only task first, then a simple click or type task.
  202. 7. Keep the visual overlay enabled while evaluating behavior.
  203. If a site uses heavy client rendering, custom canvas controls, or unusual shadow DOM, start by asking FSB to read the page and identify available controls. That gives the model a better first snapshot and makes failures easier to debug.
  204. ### Quick Troubleshooting
  205. | Problem | Check |
  206. |---------|-------|
  207. | Extension does not appear | Confirm Chrome loaded `extension/`, not the repo root. |
  208. | API test fails | Confirm the selected provider, key, endpoint, and model belong together. |
  209. | Page reads fail | Move away from browser-internal pages such as `chrome://` or extension pages. |
  210. | Clicks miss targets | Refresh the DOM snapshot, scroll the target into view, or use coordinate tools. |
  211. | Typed text does not stick | Prefer `type_text` over JavaScript value assignment on controlled inputs. |
  212. | MCP tools are missing | Restart the host client and run `npx -y fsb-mcp-server@latest doctor`. |
  213. | MCP tools time out | Check `status --watch`, active tab readiness, and whether another task is queued. |
  214. Most failures are recoverable by inspecting the current page, refreshing selectors, or restarting the local MCP bridge. Reinstalling the MCP config should be the last step, not the first.
  215. ### Local Development Setup
  216. You do not need a build step to load the extension in Chrome. You only need npm dependencies when running tests, building MCP, or building the showcase site.
  217. ```bash
  218. npm install
  219. npm --prefix mcp install
  220. npm --prefix showcase/angular install
  221. ```
  222. The extension reads bundled scripts directly from `extension/`. The MCP package is TypeScript and must be built before smoke tests or npm publishing. The showcase is a normal Angular app with static prerender output served by the production Express backend.
  223. ---
  224. ## MCP Server
  225. FSB ships [`fsb-mcp-server`](https://www.npmjs.com/package/fsb-mcp-server), a local MCP server that lets external AI clients control the same browser extension. It exposes 69 registered tools across autopilot, trigger watchers, manual browser control, read-only page inspection, task outcome reporting, Developer/UAT capture, capability search/invoke, observability, and vault.
  226. The extension connects to the MCP bridge on:
  227. ```text
  228. ws://localhost:7225
  229. ```
  230. Optional Streamable HTTP mode exposes:
  231. ```text
  232. http://127.0.0.1:7226/mcp
  233. ```
  234. The HTTP endpoint binds to loopback only and rejects requests with an `Origin` header or a foreign `Host`. Use the printed local endpoint from an MCP client. If a tab stops responding, page reads return `PAGE_UNRESPONSIVE`; `navigate` and `close_tab` remain available. Inspect page state before repeating any action reported as `outcome: "unknown"` and `mayHaveExecuted: true`.
  235. ### One Command Install
  236. ```bash
  237. npx -y fsb-mcp-server@latest install --claude-desktop
  238. npx -y fsb-mcp-server@latest install --claude-code
  239. npx -y fsb-mcp-server@latest install --cursor
  240. npx -y fsb-mcp-server@latest install --vscode
  241. npx -y fsb-mcp-server@latest install --antigravity
  242. npx -y fsb-mcp-server@latest install --codex
  243. npx -y fsb-mcp-server@latest install --cline
  244. npx -y fsb-mcp-server@latest install --all
  245. ```
  246. Preview without writing:
  247. ```bash
  248. npx -y fsb-mcp-server@latest install --all --dry-run
  249. npx -y fsb-mcp-server@latest install --list
  250. ```
  251. ### Manual Examples
  252. Claude Code:
  253. ```bash
  254. claude mcp add --scope user fsb -- npx -y fsb-mcp-server@latest
  255. ```
  256. Codex (`~/.codex/config.toml`):
  257. ```toml
  258. [mcp_servers.fsb]
  259. command = "npx"
  260. args = ["-y", "fsb-mcp-server@latest"]
  261. ```
  262. VS Code (`mcp.json`):
  263. ```json
  264. {
  265. "servers": {
  266. "fsb": {
  267. "type": "stdio",
  268. "command": "npx",
  269. "args": ["-y", "fsb-mcp-server@latest"]
  270. }
  271. }
  272. }
  273. ```
  274. Cline (`~/.cline/data/settings/cline_mcp_settings.json`, shared by the VS Code extension, JetBrains plugin, and CLI). `timeout` is in seconds; Cline's 60-second default would cut off long `run_task` calls:
  275. ```json
  276. {
  277. "mcpServers": {
  278. "fsb": {
  279. "command": "npx",
  280. "args": ["-y", "fsb-mcp-server@latest"],
  281. "timeout": 1800
  282. }
  283. }
  284. }
  285. ```
  286. Diagnostics:
  287. ```bash
  288. npx -y fsb-mcp-server@latest doctor
  289. npx -y fsb-mcp-server@latest status --watch
  290. npx -y fsb-mcp-server@latest wait-for-extension
  291. ```
  292. See [mcp/README.md](mcp/README.md) for the full tool reference and client-specific setup notes.
  293. OpenCode and OpenClaw are supported through manual or unsupported fallback setup paths; after editing host configuration, refresh or reload the client if FSB tools do not appear.
  294. ### MCP Usage Guidance
  295. Manual tools are the default path for most external clients. They let the caller inspect the page, pick a selector, act, and verify. `run_task` is useful when the user explicitly wants FSB to run its own automation loop, but manual control is easier to audit and recover.
  296. Use Trigger Watchers when a caller wants to watch one selector for a future value change instead of polling manually. They are local to the open browser session: Chrome and the FSB extension must remain running, results are reported back to the MCP caller, and FSB does not provide server-side monitoring or push delivery.
  297. Recommended manual pattern:
  298. 1. Add `visual_reason` and `client` on action calls when you want the trusted overlay.
  299. 2. `read_page` or `get_dom_snapshot` to understand the current page.
  300. 3. Use `execute_js` for safe DOM reads and simple DOM-triggered clicks.
  301. 4. Use native tools such as `click`, `type_text`, `press_key`, and `drag` when real browser events matter.
  302. 5. Verify with `read_page`, `get_page_snapshot`, or `get_dom_snapshot`.
  303. 6. Set `is_final:true` on the last action to clear the overlay immediately.
  304. Use `doctor` and `status --watch` before changing client configs. Most MCP failures are connection, extension wake, active-tab, or content-script readiness issues, not install problems.
  305. ---
  306. ## Architecture
  307. ```mermaid
  308. graph TB
  309. UI["Popup / Side Panel / Options"] --> BG["MV3 Background Worker"]
  310. BG --> AI["Universal Provider"]
  311. BG --> CS["Content Scripts"]
  312. BG --> MEM["Memory + Analytics"]
  313. BG --> MCP["MCP Bridge"]
  314. AI --> APIs["xAI / Gemini / OpenAI / Anthropic / OpenRouter / Local"]
  315. CS --> PAGE["Web Page DOM"]
  316. MCP --> CLIENTS["Claude Code / Codex / Cursor / VS Code / Others"]
  317. ```
  318. ### Main Runtime Pieces
  319. - **Background worker** (`extension/background.js`): owns sessions, model calls, tool execution, MCP routing, and storage orchestration.
  320. - **Content scripts** (`extension/content/`): analyze the DOM, create element references, execute actions, stream DOM state through the PhantomStream capture adapter, wait for stable state, and render visual feedback.
  321. - **AI layer** (`extension/ai/`): universal OpenAI-compatible request engine, provider settings, model discovery, tool definitions, transcripts, and action history.
  322. - **Memory** (`extension/lib/memory/`): stores episodic, semantic, and procedural records, then retrieves relevant prior context for later tasks.
  323. - **Visualization** (`extension/lib/visualization/`): D3/site graph views for guide and memory exploration.
  324. - **Vault** (`extension/config/secure-config.js` plus UI flows): encrypts API keys and saved user data in Chrome storage.
  325. - **MCP package** (`mcp/`): TypeScript server that translates MCP calls into extension bridge messages.
  326. ### Automation Flow
  327. 1. User or MCP client submits a task.
  328. 2. FSB captures the active page structure.
  329. 3. Relevant site guides and memory are retrieved.
  330. 4. The selected model plans the next tool call.
  331. 5. Content scripts execute browser actions and wait for visible change.
  332. 6. FSB verifies the result, records analytics, and either continues or finishes.
  333. ### State And Data Flow
  334. FSB stores configuration and runtime data in Chrome storage. API keys and saved sensitive values go through the secure configuration layer. Session logs, analytics, and memory records are kept locally unless a user explicitly enables server sync or uses the showcase dashboard pairing flow.
  335. During a task, the background worker owns the session state and talks to three main collaborators:
  336. - content scripts for page reads and browser actions
  337. - the selected provider for planning and response generation
  338. - local storage for config, analytics, memory, and logs
  339. The MCP server does not replace the extension runtime. It is a local bridge that translates MCP requests into the same background-worker routes used by FSB's own UI.
  340. ### Browser Action Surface
  341. The extension's canonical tool registry covers navigation, search, clicking, typing, keyboard events, scrolling, waiting, tabs, spreadsheets, coordinate interactions, real file uploads, DOM mutation helpers, read-only inspection, site guide lookup, memory search, and task finalization signals.
  342. The MCP server exposes a curated public surface around that registry plus direct server-registered companion tools:
  343. | Surface | Count | Examples |
  344. |---------|-------|----------|
  345. | Autopilot | 3 | `run_task`, `stop_task`, `get_task_status` |
  346. | Trigger watchers | 4 | `trigger`, `stop_trigger`, `get_trigger_status`, `list_triggers` |
  347. | Manual control | 37 | `execute_js`, `navigate`, `click`, `type_text`, `drag`, `upload_file` |
  348. | Read-only inspection | 8 | `read_page`, `get_dom_snapshot`, `get_site_guide`, `read_sheet` |
  349. | Task outcome | 3 | `complete_task`, `partial_task`, `fail_task` |
  350. | Developer / UAT | 1 | `capture_screenshot` |
  351. | Capabilities | 2 | `search_capabilities`, `invoke_capability` |
  352. | Observability and replay | 7 | `list_sessions`, `get_session_replay`, `replay_session` |
  353. | Vault | 4 | `list_credentials`, `fill_credential`, `use_payment_method` |
  354. Read-only tools bypass the mutation queue where safe. `capture_screenshot` is semantically read-only but remains serialized because it consumes Chromium's exclusive debugger resource. Mutation tools are serialized so two clients do not click, type, upload, invoke, or navigate at the same time. Capability tools remain outside the canonical extension registry by design; `search_capabilities` bypasses the queue, while `invoke_capability` serializes like other side-effecting tools. Search results include readiness labels so callers can distinguish `t1-ready` direct execution from `t1-guarded-fail-closed`, `learn-pending`, and `discovery-pending` catalog-tail hits.
  355. `capture_screenshot` captures Chromium's actual composited page, not reconstructed HTML. MCP returns a native PNG image plus a private managed file in `~/.fsb/screenshots`; matching files expire after seven days. Autopilot does not create a file: screenshot bytes live only in service-worker memory until the next model request and are excluded from transcripts, history, logs, metrics, and persistence. A screenshot can contain sensitive visible page data, so share or upload the returned path only when the destination is trusted.
  356. Recorded MCP tasks can span multiple tabs while remaining one logical history session. The task lifecycle (`complete_task`, `partial_task`, or `fail_task`) closes that history record; `is_final` only clears the visual overlay, with idle expiry as a recording fallback. `get_session_replay` exposes the verified, receipt-free replay structure; `replay_session` requests one exact-manifest approval in the FSB side panel, after which FSB opens and maps the recorded tabs automatically.
  357. ---
  358. ## AI Providers
  359. FSB uses one universal provider path for hosted, routed, local, and custom OpenAI-compatible models.
  360. | Provider | Default or fallback model | Notes |
  361. |----------|---------------------------|-------|
  362. | xAI | `grok-4-1-fast` | Default provider, fast automation profile. |
  363. | Google Gemini | `gemini-2.5-flash` | Includes free/low cost model options depending on Google availability. |
  364. | OpenAI | `gpt-4o` | Strong general automation and structured output. |
  365. | Anthropic | `claude-sonnet-4-6` | Strong reasoning and form-heavy workflows. |
  366. | OpenRouter | `openai/gpt-4o` | Single key for routed models; live discovery supported. |
  367. | LM Studio | Live local model list | No API key; reads `/v1/models` from a local LM Studio server. |
  368. | Custom | User supplied model | Any compatible chat completions endpoint. |
  369. The extension includes 30 fallback model entries and live model discovery for supported hosted providers. Pricing and model availability change frequently, so use the provider dashboard as the source of truth for billing.
  370. ### Provider Configuration Notes
  371. - xAI, Gemini, OpenAI, Anthropic, and OpenRouter use API keys saved in Chrome storage.
  372. - LM Studio requires the local server to be enabled and reachable from Chrome.
  373. - Custom endpoints should point to a chat completions-compatible URL.
  374. - The saved model is preserved even when it is not in the bundled fallback list, so newly discovered models are not silently overwritten after a service worker restart.
  375. - If discovery fails, the options page falls back to bundled models and shows the discovery status inline.
  376. Provider-specific prompt formatting lives in the AI layer, but the execution loop is intentionally shared. That keeps action planning, tool validation, transcript storage, cost tracking, and error handling consistent across models.
  377. ### Model Discovery And Fallbacks
  378. Model discovery queries provider model endpoints where available, filters non-text models, normalizes the list, and caches successful results. If a provider is offline, the key is missing, or discovery fails, FSB keeps the UI usable with bundled fallback models.
  379. The fallback table currently includes:
  380. - 6 xAI models
  381. - 5 Gemini models
  382. - 4 OpenAI models
  383. - 9 Anthropic models
  384. - 6 OpenRouter presets
  385. - live-only LM Studio models
  386. Custom providers are intentionally open-ended. The model name and endpoint come from user settings, and the universal provider handles OpenAI-compatible request/response behavior.
  387. ---
  388. ## Site Intelligence And Memory
  389. FSB ships site guides for 17 categories, including ecommerce, finance, social, travel, coding, email, career, gaming, productivity, media, design, news, utilities, sports, reference, music, and games. Guides provide selectors, navigation patterns, workflow hints, and known site quirks.
  390. Long term memory records:
  391. - **Episodic**: what happened in a specific session.
  392. - **Semantic**: facts learned about a domain or UI.
  393. - **Procedural**: repeatable workflows and selectors that worked.
  394. Memory operations are tracked separately from normal automation costs. The options dashboard exposes usage charts, memory detail panels, logs, and export controls.
  395. ### Guide Categories
  396. | Category | Examples |
  397. |----------|----------|
  398. | Ecommerce | Amazon, eBay, Walmart, Best Buy, Target |
  399. | Finance | Yahoo Finance, TradingView, Google Finance, Coinbase |
  400. | Social | YouTube, Reddit, LinkedIn, Instagram, TikTok |
  401. | Travel | Booking, Kayak, Google Travel, Airbnb, airlines |
  402. | Coding | GitHub, Stack Overflow, LeetCode, Codeforces |
  403. | Email and productivity | Gmail, Outlook, Google Workspace, Notion, Jira, Trello |
  404. | Career | Workday, Greenhouse, Lever, major employer job portals |
  405. | Media and design | Video players, voice recorders, Photopea, Miro, Excalidraw |
  406. | Edge cases | CAPTCHA-like sliders, file upload, cookie opt-out, buried login links |
  407. Site guides are helpers, not hard-coded scripts. FSB still reads the current DOM each turn and uses guides as context for better selectors and fewer repeated mistakes.
  408. ### Memory Lifecycle
  409. After a task, FSB can extract memories from the session transcript and action history. Memories are scored, tagged, consolidated, and later retrieved by domain, task type, recency, and keyword relevance. This lets FSB reuse what it learned without stuffing every previous session into every prompt.
  410. Memory and site maps are especially useful for:
  411. - repeated workflows on the same domain
  412. - pages with custom controls or unstable selectors
  413. - identifying successful login, search, checkout, or form-fill patterns
  414. - avoiding known bad selectors or repeated failed actions
  415. - visualizing learned site structure from the options dashboard
  416. ---
  417. ## Security And Safety
  418. - API keys are encrypted with AES-GCM and stored in Chrome storage.
  419. - Credential and payment vault flows avoid sending raw secrets over the MCP bridge.
  420. - Rendered chat output is sanitized with DOMPurify.
  421. - Automation is scoped to the active session tab where possible.
  422. - Logs can be reviewed or disabled for sensitive use cases.
  423. Use separate API keys for development and production, rotate keys regularly, respect website terms of service, and supervise automation on anything account, finance, shopping, or data-entry related.
  424. ### Current Boundaries
  425. - FSB does not bypass browser restrictions on internal pages.
  426. - CAPTCHA solving support is a framework and optional service integration, not a guarantee.
  427. - The extension can interact with the active page, tabs, and debugger-backed coordinate tools because those permissions are declared in the MV3 manifest.
  428. - `upload_file` requires an absolute local path, blocks known sensitive path patterns, and records audit metadata without persisting the disk path.
  429. - Capability invokes allow every non-denied origin under Auto and run through denylist, mutation, signature, and audit gates. Only verified T1/T1b capabilities execute directly; guarded or catalog-tail capabilities return typed pending/fallback responses. Sensitive origins are flagged for review; network-capture discovery on sensitive origins still requires extra confirmation.
  430. - Saved credentials and payment methods require explicit user configuration and unlock flows.
  431. - Automation should be treated like a fast assistant operating your browser, not like an unattended production worker.
  432. ### Data Handling
  433. Provider calls receive the page/task context needed to complete the requested automation. That can include visible page text, form labels, selectors, and user-supplied task instructions. Avoid running automation on sensitive pages unless you are comfortable sending that task context to the selected model provider.
  434. FSB does not require a hosted FSB account for local extension use. The showcase backend and dashboard pairing server are separate from normal local extension operation.
  435. ---
  436. ## Development
  437. Install root dependencies when running validation or tests:
  438. ```bash
  439. npm install
  440. npm --prefix mcp install
  441. npm --prefix showcase/angular install
  442. ```
  443. Common checks:
  444. ```bash
  445. npm run validate:extension
  446. npm test
  447. npm run test:mcp-smoke
  448. npm --prefix showcase/angular run build
  449. ```
  450. The CI workflow runs these checks in separate jobs:
  451. - extension validation and Node tests
  452. - MCP TypeScript build and smoke tests
  453. - Angular showcase build
  454. Other useful commands:
  455. ```bash
  456. npm run showcase:serve
  457. npm run showcase:smoke
  458. npm --prefix mcp run build
  459. npm --prefix mcp run dev
  460. ```
  461. Debugging:
  462. - Inspect the service worker from `chrome://extensions/`.
  463. - Check the browser console on the active tab for content script logs.
  464. - Use the options page log viewer for session and action history.
  465. - For MCP issues, run `npm run test:mcp-smoke`, then `npx -y fsb-mcp-server@latest doctor`, then `npx -y fsb-mcp-server@latest status --watch`.
  466. ### Change Guidelines
  467. - Keep behavior-specific docs close to the package that owns the behavior.
  468. - Update the root README only for public setup, architecture, or feature changes.
  469. - Update `mcp/README.md` when tool names, counts, transports, diagnostics, or installer platforms change.
  470. - Update `extension/README.md` when manifest entry points, extension loading, packaging, or validation changes.
  471. - Update `showcase/README.md` when Angular, deploy, crawler, or site build behavior changes.
  472. - Prefer tests for any shared contract between the extension and MCP server; stale docs are usually symptoms of missing contract checks.
  473. ### Release Sanity Checks
  474. Before changing a release version, author its release entry in the owning changelog, then run `npm run version:set:extension -- X.Y.Z` or `npm run version:set:mcp -- X.Y.Z`. Release notes remain human-authored and the setters do not rewrite changelog history. Before cutting either release, run `npm run version:check` and verify:
  475. - extension-owned metadata matches `extension/manifest.json`, while MCP-owned metadata matches `mcp/package.json`
  476. - `extension-vX.Y.Z` and `mcp-vX.Y.Z` tags match their independently versioned artifacts
  477. - README version badges and "what's new" sections match package metadata
  478. - screenshots and logos resolve from tracked paths
  479. - MCP README tool counts match the registered runtime surface
  480. - showcase README matches Angular major version and build output path
  481. - no retired background-agent behavior is advertised as active functionality
  482. ### Documentation Ownership
  483. The root README should describe what a new user needs to understand before installing, testing, or choosing an integration path. Detailed package behavior belongs in the package README that owns it. This split keeps the public overview useful while still giving maintainers a clear place to update tool surfaces, extension entry points, or showcase deploy instructions.
  484. ---
  485. ## Acknowledgements
  486. - **OpenTabs** inspired FSB's Native Capability Catalog (first-party API execution: turning authenticated browser sessions into reusable, signed, audited API capabilities). Thanks for the direction on this approach.
  487. ## License
  488. This project is licensed under the MIT License. See [LICENSE](LICENSE).
  489. ## Support And Contributing
  490. - Report bugs and feature requests in [GitHub Issues](https://github.com/fullselfbrowsing/FSB/issues).
  491. - Include the task prompt, target site, provider/model, logs, and reproduction steps where possible.
  492. - Pull requests should update tests and docs when behavior, setup, or public interfaces change.
  493. <div align="center">
  494. **Made by [Lakshman Turlapati](https://github.com/lakshmanturlapati)**
  495. *FSB Full Self Browsing: AI powered automation, accessible to everyone.*
  496. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.