Show HN: BrowserForge – AI agents use your real browser, you approve the clicks

BrowserForge, a local-first Firefox and Chrome extension paired with an MCP server, launched for Claude Code, OpenAI Codex and other MCP clients, letting AI agents operate inside a user's real browser session while requiring a human click to approve consequential actions such as submits, payments, password entry and uploads. The tool runs entirely on 127.0.0.1 with no cloud service or API credits, requires Node.js 22 or newer, and captures observed traffic to generate an OpenAPI 3.1 spec plus Python, TypeScript, JavaScript and PHP clients, labeling each inferred API fact as observed, inferred or hypothesis with confidence and evidence. BrowserForge ships on the Chrome Web Store for Chrome, Edge and Brave and on Firefox Add-ons, and its Windows installer is not yet code-signed.

Give your AI agent a real browser, and turn the traffic it sees into API docs and clients. A local-first Firefox + Chrome extension and MCP server for Claude Code, OpenAI Codex and any other MCP client. Chrome, Edge and Brave use the Chrome Web Store build. Then install the small local program: on Windows run the installer above it brings its own Node.js; Windows may warn because it is not code-signed yet: More info , then Run anyway , elsewhere see Quick start quick-start . <sub The approval step 12 s . Watch the full 73-second demo MP4 https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/assets/demo.mp4 : fill a form, approve the submit, turn traffic into an OpenAPI spec, open the dashboard. Recorded on the demo site in this repo; a script plays the agent. Re-record it with npm run demo:record .</sub AI agents are good at deciding what to do on a website and bad at being trusted with your accounts. BrowserForge closes that gap: the agent works in your real browser through an extension, a small local program carries its requests, and you approve anything consequential submit, send, pay, passwords, uploads with a click the agent cannot answer. What the agent sees and learns stays on your computer and is turned into reusable things: replayable flows , shareable skills , and API specs and clients built from the traffic it observed. The longer story, how this differs from headless automation and other browser bridges, and where the project is going: docs/VISION.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/VISION.md . | Real browser, real session | A WebExtension, not a headless clone: your tabs, your logins, your cookies. | | Local-first | Everything runs on 127.0.0.1 . No cloud service, no API credits. | | Reverse-engineer APIs | Capture traffic, then get endpoints, schemas, auth and pagination, an OpenAPI 3.1 spec and Python / TypeScript / JavaScript / PHP clients. | | Human in the loop | Submitting forms, purchases, sending, accepting terms, passwords and uploads wait for a click in the extension popup that the agent cannot answer. A red STOP halts the agent until you resume. | | Honest output | Every inferred API fact is labelled observed , inferred or hypothesis with confidence and evidence. Per-browser capture limits are documented in docs/LIMITATIONS.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/LIMITATIONS.md . | | Secure by default | Token-authenticated loopback transports, Origin/Host checks, strict schemas, secret redaction, path-safe file access. See docs/SECURITY.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/SECURITY.md . | Requires Node.js 22 or newer, and Chrome, Edge, Brave or Firefox, on Linux, macOS or Windows Linux is the one it has been tested on; see docs/INSTALL.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/INSTALL.md . From npm no build : npm install -g @el-makina-ai/browserforge-mcp then: browserforge setup From a checkout: npm install && npm run build node apps/mcp-server/dist/cli.js serve prints endpoints, creates tokens in ~/.config/browserforge/ node apps/mcp-server/dist/cli.js tokens shows the extension token 1. Install the extension from the store: - Chrome Web Store https://chromewebstore.google.com/detail/browserforge/ihbkpcclcolaeppmfgmndmemjljmiaec Chrome, Edge, Brave - Firefox Add-ons https://addons.mozilla.org/en-US/firefox/addon/browserforge/ Working from a checkout? Load your own build instead: - Firefox: about:debugging /runtime/this-firefox → Load Temporary Add-on → apps/firefox-extension/dist/firefox/manifest.json - Chrome: chrome://extensions → Developer mode → Load unpacked → apps/firefox-extension/dist/chrome 2. Connect it. Click the toolbar icon, paste the extension token , press Connect . 3. Connect your agent. Guides: Codex https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/CODEX.md · Claude Code https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/CLAUDE CODE.md codex mcp add browserforge --url http://127.0.0.1:7345/mcp --bearer-token-env-var BROWSERFORGE MCP TOKEN claude mcp add --transport http browserforge http://127.0.0.1:7345/mcp --header "Authorization: Bearer $ cat ~/.config/browserforge/mcp-token " 4. Try it. Start the demo site with node tests/fixtures/demo-site/server.mjs , then ask your agent:Call system status , then open http://127.0.0.1:8099/apply and describe the form. Full instructions: docs/INSTALL.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/INSTALL.md · guides in the wiki https://github.com/zoghlamimostafa/BrowserForge-MCP/wiki · what is planned: the roadmap board https://github.com/users/zoghlamimostafa/projects/1 . Problems: docs/TROUBLESHOOTING.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/TROUBLESHOOTING.md . - "Open this site, click through the checkout flow, and tell me which API calls it makes." - "Analyze the captured traffic and generate an OpenAPI spec and a Python client for the endpoints I used." - "Fill in the application form from my saved profile, show me a preview, and wait for my approval before submitting." - "Export the capture as a HAR file with secrets redacted." From a website to a working API client , in one conversation: the agent browses the shop, BrowserForge analyses the requests it saw by code, not a model , writes an OpenAPI spec and a Python client that passes its own tests, and the client fetches real data: Watch the 41-second API demo MP4 https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/assets/demo-api.mp4 . Recorded on the demo site in this repo with npm run demo:record -- --scene api ; a script plays the agent. More end-to-end examples: docs/WORKFLOWS.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/WORKFLOWS.md . | Namespace | Tools | |---|---| | browser | browser get tabs , browser get active tab , browser select tab , browser close tab , browser navigate , browser click , browser type , browser fill field , browser select option , browser scroll , browser press key , browser get page text , browser get dom snapshot , browser get interactive elements , browser take screenshot , browser wait for element , browser get forms , browser extract table , browser verify , browser fill form , browser get downloads , browser get console errors , browser solve captcha , browser pending requests , browser pause , browser resume , browser stop | | network | network list requests , network get request , network get request details , network search requests , network list captures , network configure capture , network export har , network import har , network clear capture | | api reverse engineering | api analyze traffic , api list endpoints , api get endpoint details , api generate openapi , api generate client | | form | form profile save , form profile list , form profile delete , form discover , form fill from profile , form validate , form preview submission , form prepare cover letter | | goal optional, local model | browser run goal , browser goal feedback | | knowledge | knowledge add document , knowledge search , knowledge list , knowledge remove , knowledge export dataset | | flows | flow list , flow get , flow save , flow delete , flow record , flow export , flow run , flow consolidate , flow to skill | | sites | site info , site note , site list | | skills | skill list , skill get , skill run workflow plus one prompt per skill | | plugins | whatever the plugins you install add, e.g. cv from the RenderCV plugin | | workflow | workflow create , workflow run , workflow pause , workflow resume , workflow get status | | system | system status , system diagnostics | Read-only tools carry readOnlyHint . Every tool has a strict JSON schema unknown arguments are rejected and bounded output. browser run goal is an optional fast path: local models pick one routine step at a time from a compact table of the page. By default Qwen via Ollama decides; --decider cascade puts Laya via Ollaya https://github.com/ollaya-dev/ollaya first with Qwen as backup. The run hands back to your agent when the models are unsure, and every step says which model decided. It only types values you pass in, never navigates to other sites, and goes through the same approval gate as every other action. Analysis and code generation themselves are deterministic and use no LLM. BrowserForge records what an agent does on each website as a flow : steps, several ways to find each element, and your typed values as named parameters passwords are never kept . Replay a flow with no model flow run , or export it as a script for Playwright TypeScript, Python , Selenium Python, Java , Chrome DevTools Recorder / Puppeteer Replay , or neutral JSON: browserforge flow list browserforge flow export <id --format playwright-ts --out signup.ts FLOW CONFIRM=1 FLOW PARAM FIRST NAME=Grace npx tsx signup.ts Exported scripts stop before submits, sends and uploads unless you say FLOW CONFIRM=1 , since outside BrowserForge there is no approval prompt. Details: docs/FLOWS.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/FLOWS.md . - Agent window: turn it on in the popup and the agent works in its own window instead of the tabs you are using; it can still use one of yours when it selects it on purpose. Take over stops the agent and shows its window so you can finish by hand; Hand back lets it carry on. Details: docs/AGENT WINDOW.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/AGENT WINDOW.md . - Tables: browser extract table reads HTML tables and ARIA grids also inside iframes as column names and rows, with merged cells expanded, as JSON or CSV spreadsheet formulas neutralised , or saved to a file so a big table does not fill the agent's context. - Site cards: navigating to a site returns what is known about it obstacles, past results, flows to replay ; agents add to it with site note . See docs/SITES.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/SITES.md . - Automatic checks: after a submit, and at the end of browser run goal , the page is read for a confirmation or an error, and the run is labelled good or bad without waiting for anyone. browser verify does it on demand. - Flows to skills: flow consolidate merges many recordings of a task into one clean flow, and flow to skill turns it into a shareable skill that replays with no model. - Record me: an opt-in popup switch that also records your own clicks and fields as a flow and as training examples for the local model. Off by default, passwords never recorded, everything stays on your computer. browserforge dashboard opens a read-only page on your own computer: connected browsers, MCP sessions and every tool, the plugins and skills you installed with the permissions you approved, in plain words , recorded flows and how the local models are doing. It changes nothing and has its own token. Details: docs/DASHBOARD.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/DASHBOARD.md . Anyone can add to BrowserForge without touching the core: - Skills : a folder with a SKILL.md and optional ready-made workflows . No code; agents read it. browserforge skill new my-skill . docs/SKILLS.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/SKILLS.md - Plugins : a small ES module that adds tools, with a manifest of exactly which folders, programs and browser access it needs. You see that list in plain words and approve it before it is installed; a later version asking for more is switched off until you approve again. browserforge plugin new my-tool . docs/PLUGINS.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/PLUGINS.md browserforge plugin search cv npm packages tagged "browserforge-plugin" browserforge plugin add ./plugins/rendercv browserforge plugin config rendercv cvDir=~/cv rendercv=~/venv/bin/rendercv The first plugin is plugins/rendercv https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/plugins/rendercv : tailor a RenderCV resume to each job reorder and reword only; it rejects any number, link or tool name not already in your CV , render it, and keep an application log. Its companion skill skills/job-apply https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/skills/job-apply is a worked example of a skill. Contributing: CONTRIBUTING.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/CONTRIBUTING.md . php flowchart LR A "Your agent<br/ Claude Code · Codex · any MCP client" -- |"MCP + token"| D subgraph D "browserforge daemon · 127.0.0.1" T "Tools" --- N "Traffic analyzer<br/ + client generator" T --- F "Flows" T --- M "Memory<br/ site cards · traces" T --- L "Local deciders<br/ Qwen · Laya" end D -- |"WebSocket + token"| E "Extension<br/ Chrome · Firefox<br/ approvals · STOP" N -- O "OpenAPI · API clients · HAR" F -- S "Playwright · Selenium ·<br/ Chrome Recorder scripts" F -- |"flow to skill"| K "Skills" K -- A P "Plugins<br/ permission manifests" -- T The extension, the daemon and the typed protocol between them are the core. Flows, skills and plugins are how it grows without touching the core, and the local models and site memory make repeated tasks cheaper. Each part, and where it is heading a shared library of skills, local models that learn from your demonstrations, more plugins, more browsers and platforms , is in docs/VISION.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/VISION.md . Claude Code / Codex ──MCP HTTP + Bearer ──► browserforge daemon ──WebSocket token + Origin ──► extension in Firefox / Chrome MCP tools · BrowserHub background · content script · popup NetworkStore · analyzer · generator approvals · STOP 1. A tool call is validated against its schema, then sent to the extension with a request id, timeout and cancellation. 2. The extension re-validates it, resolves the tab and element, and runs it in the page. 3. If the action looks consequential, it returns to the human for approval inside the browser before anything happens. 4. Results flow back to the agent as redacted, bounded, untrusted data. Deeper dive: docs/ARCHITECTURE.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/ARCHITECTURE.md · docs/BROWSER PROTOCOL.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/BROWSER PROTOCOL.md · docs/RESEARCH.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/RESEARCH.md . - Page content is data, never instructions. It is wrapped as untrusted before the agent sees it. - Approvals live in the browser. The agent cannot answer the popup. - Secrets are redacted from what the agent sees, from exports and from generated code. Revealing them requires starting the daemon with --allow-reveal . - Nothing is persisted unless you export it. Captured traffic stays in memory. - No anti-bot evasion and no arbitrary-JavaScript tool. CAPTCHA solving exists only as the opt-in browser solve captcha local CapSkip app, needs --capskip and YOLO mode; see SECURITY.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/SECURITY.md . apps/firefox-extension cross-browser extension source builds dist/firefox and dist/chrome apps/mcp-server daemon: MCP HTTP/stdio , extension WebSocket hub, tools, CLI packages/browser-protocol versioned Zod message and action schemas packages/network-inspector capture store, filters, redacted views, HAR packages/api-analyzer traffic to endpoints, schemas, pagination, auth, evidence packages/client-generator OpenAPI 3.1, Python/TS/JS/PHP clients, safe writer, validators packages/knowledge local reference documents BM25 and run traces packages/flows flow format, builder and exporters Playwright, Selenium, Chrome Recorder, JSON packages/plugin-sdk what plugin authors import: manifest, permission-checked api, test helper plugins/ reference plugins rendercv skills/ reference skills job-apply packages/shared errors, limits, redaction, path safety, tokens, logger tests/ unit · security · integration · e2e real browsers · demo site docs/ examples/ CONTRIBUTING.md | Command | What it does | |---|---| | npm run build | TypeScript project build and extension bundles | | npm run typecheck | tsc for packages, server, extension and tests | | npm run lint | ESLint and web-ext lint | | npm test | unit, security and integration tests no browser needed | | npm run test:e2e | real Firefox geckodriver and Chromium Playwright ; BF BROWSERS=firefox to pick one | | npm run package | artifacts/browserforge-{firefox,chrome}-<version .zip | | npm run dev | rebuild on change and restart the daemon | Version 0.2.1 the Chrome Web Store and Firefox Add-ons are updated after each release , published on the Chrome Web Store and Firefox Add-ons. BrowserForge reports what a WebExtension can actually see; it does not capture all browser traffic. For example, Firefox cannot observe WebSocket frames, closed shadow roots and sandboxed iframes are invisible to it, and consequential-action detection is heuristic. Read docs/LIMITATIONS.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/LIMITATIONS.md for the full list and docs/RELEASE CHECKLIST.md https://github.com/zoghlamimostafa/BrowserForge-MCP/blob/main/docs/RELEASE CHECKLIST.md for the manual checks still required before a release. Use BrowserForge only on sites and accounts you are authorised to automate or inspect, and respect their terms of service and the law. It is built for your own sessions and for legitimate testing, integration and documentation work. If BrowserForge saves you time, a ⭐ on this repository helps other people find it. Ideas, questions and plugins are welcome in Discussions https://github.com/zoghlamimostafa/BrowserForge-MCP/discussions ; things you can pick up right now are the issues marked help wanted https://github.com/zoghlamimostafa/BrowserForge-MCP/issues?q=is%3Aopen+label%3A%22help+wanted%22 , and the plan is on the roadmap board https://github.com/users/zoghlamimostafa/projects/1 .