Savvy-Tech-Sphere/usable-browser-agent-free

An MCP server plus a browser extension that lets your AI agent (Claude Code, Codex, or any MCP
client) drive **your real browser**, with all your logged-in sessions, instead of a throwaway
automated browser. You log in once, by hand, and the agent operates as you.
This repository is the **free tier**: the same single-session MCP server as the commercial
build, licensed for personal, non-commercial use and for evaluating the product before buying.
The Firefox extension for it is published on Firefox Add-ons. Commercial use (in or for a
business, in paid client work, or inside a commercial product or service) needs the commercial
license, a one-time $39 purchase at , which
also includes the Chrome build. It comes with a 14-day, no-questions refund. There is no license
key in either tier and nothing checks for one; the tiers differ only in the license grant and
the extension identity.
> **Your passwords stay out of the agent.** When the agent logs you in, it passes only a secret
> *alias*, never the value. Credentials live in a local vault, are domain-locked (refused on the
> wrong site), and are redacted from everything the agent reads or screenshots. See
> docs/CREDENTIAL-SAFETY.md.
How it works
The agent perceives pages through an accessibility/DOM snapshot where every interactive element
has a stable [ref=eN] handle, then clicks and types by ref. No coordinate guessing, no vision
model required. Everything runs on your machine: MCP over stdio, and the extension talks to the
server over a WebSocket bound to 127.0.0.1. Nothing leaves your computer.
The agent always acts on the currently active tab. Keep the tab you want it to use focused.
Get started (about 2 minutes)
Two pieces: this **MCP server**, which your agent launches, and the **Firefox extension**, which
you install once from Firefox Add-ons.
1. Get the server and run the installer
Needs Node.js 18 or newer and Firefox 142 or newer (macOS first; see
docs/INSTALL.md).
Or from a checkout of this repository:
(Prefer a download? Grab the zip from the
Releases page, unpack
it, and run the same command inside the folder.)
The installer checks Node and the port, installs dependencies, registers the MCP server with
**Claude Code** and/or **Codex** using this copy's absolute path, runs the smoke test, optionally
stores your first login, and prints the macOS permission steps. It is idempotent; re-running it
never clobbers an existing config. Pass --non-interactive to accept every default.
2. Install the Firefox extension (one time)
Install **Usable Browser Agent (free)** from Firefox Add-ons:
The toolbar badge shows **off**, then **ON** once the extension connects to the MCP server your
agent launched. (The installer also prints these steps, plus the .xpi and Chrome steps that
apply to the commercial bundle; for the free tier the Add-ons listing is all you need.)
3. Log in and go
Log into the site(s) you want the agent to use, then ask your agent to run a browser task, for
example: *"On the active tab, open my notifications and list the pull requests waiting on me."*
It will snapshot the page, then act by ref.
Wiring by hand instead of the installer:
Help: docs/INSTALL.md, docs/TROUBLESHOOTING.md,
docs/UNINSTALL.md.
Hardened mode is the default
browser_eval (arbitrary JavaScript in the page) is off unless you opt in, and screenshots are
blocked near password fields. CAPTCHAs, anti-bot walls and two-factor prompts are deliberately not
automated: the agent asks you to step in, since it is your browser on your screen. One active tab
at a time.
Usage
1. Open Firefox or Chrome, log into the site(s) you want the agent to use.
2. Make sure the extension badge shows **ON**.
3. Ask Claude Code / Codex to do something — e.g. *"On the active tab, search for X and add the
first result to the cart."* It will snapshot the page, then act by ref.
Workflow memory
Usable Browser Agent keeps a local workflow memory so agents do not rediscover the same changing
website flow every time. This is for reusable task knowledge such as "how to create a new app in
Google Play Console", including current page names, visible button labels, gotchas, and successful