G9BrowserAgent

Let your AI agent use a real browser — your own, or one it starts in the background — to test, debug and automate web apps. Every click is visible, recorded and replayable.

فارسی · Download · Technical reference · Operator guide · MIT license

Contents

• What G9BrowserAgent is

• How the parts fit together

• Supported systems

• Install

• First-time setup

• Add the extension to your browser

• Connect your AI client (MCP)

• Your first session

• The side panel

• The desktop app

• How an agent drives the browser

• A browser on a server

• Browser profiles

• Updates

• Troubleshooting

• Uninstall and reset

• For developers

• Security and privacy

• Known limitations

Related MCP server: chrome-mcp

What G9BrowserAgent is

AI coding agents (Claude Code, Cursor, VS Code, Claude Desktop and others) can write a web app, but they cannot see it. G9BrowserAgent gives them a browser they can use the way a person does: open a page, read it, click, type, scroll, check the console and the network, take screenshots, and record what they did so it can be replayed later as a test.

What makes it different:

• Your own browser, or a background one. An agent can work in the Edge or Chrome you are using (with your logins), through a small extension. Or it can start its own browser in the background — no window, nothing on your screen to disturb — for long or unattended runs.

• Input like a person's. Mouse paths curve, clicks have a natural rhythm, typing has a pace. Pages react as they would to a real user, and a seed makes a run repeatable.

• Tests that survive a redeploy. A recorded flow remembers every element in several ways, so a changed CSS class does not break it. A replay says which way still matched, and what was new or missing compared with the last approved run.

• Evidence. Screenshots, console, failed requests, the DOM, and a frame-by-frame replay with the cursor drawn in. Filing an issue captures all of it in one click.

• Many agents, one browser layer. One small background service (the daemon) serves every agent on the machine. Each tab has one owner at a time, and a Stop button halts everything at once.

G9BrowserAgent runs entirely on your machine. It sends nothing anywhere; the only network access it needs is to the pages you test (and, when you ask for it, the Chrome for Testing download and the update check).

How the parts fit together

 Your AI client (Claude Code, Cursor, …)
        │  MCP (the standard way AI clients use tools)
        ▼
 G9BrowserAgent MCP shim ──────┐
 G9BrowserAgent desktop app ───┤  WebSocket, on this machine only (127.0.0.1:8765)
 G9BrowserAgent runner (CLI) ──┤
                   ▼
            G9BrowserAgent daemon (g9d) ─────────────► Engine 2: a browser G9BrowserAgent starts itself
                   │                        (Edge, Chrome or Chrome for Testing; headless by default)
                   └─────────────────────► Engine 1: the G9BrowserAgent extension in YOUR Edge or Chrome

Supported systems

Browsers: Microsoft Edge or Google Chrome 125 or newer, or the pinned Chrome for Testing that G9BrowserAgent can download for you. Firefox and Safari are not supported.

G9BrowserAgent was built and measured mostly on Windows 11. The macOS and Linux packages are built, tested and update-tested automatically on every release (see Known limitations).

Install

Download the file for your system from the latest release.

The packages are not code-signed yet, so Windows and macOS ask once before the first start. That is expected; the steps below say what to click. Each release lists the SHA-256 of every file, if you want to check your download.

Windows

1. Run G9BrowserAgent-Setup-<version>.exe.

2. If "Windows protected your PC" appears: click More info, then Run anyway.

3. G9BrowserAgent installs to %LOCALAPPDATA%\Programs\G9BrowserAgent and starts. No administrator rights are needed.

macOS

1. Open the .dmg for your Mac (arm64 for Apple silicon — M1 and newer — x64 for Intel).

2. Drag G9BrowserAgent into Applications. Start it from Applications, not from the disk image — otherwise macOS runs it from a temporary copy, and your AI clients could not find it later.

3. The first time, macOS says it "cannot check G9BrowserAgent for malicious software". Right-click (or Control-click) G9BrowserAgent in Applications → Open → Open. (Or: System Settings → Privacy & Security → Open Anyway.)

4. If macOS says G9BrowserAgent "is damaged", the download was quarantined. Run this once in Terminal: xattr -dr com.apple.quarantine /Applications/G9BrowserAgent.app

Linux — AppImage (any distribution)

1. Put G9BrowserAgent-x86_64.AppImage wherever you keep programs (for example ~/Applications). Keep the file name as it is: updates replace this exact file, and your AI clients point at it.

2. Make it executable and start it:

   chmod +x G9BrowserAgent-x86_64.AppImage
   ./G9BrowserAgent-x86_64.AppImage

3. If it says "AppImages require FUSE to run": sudo apt install libfuse2 (on Ubuntu 24.04: sudo apt install libfuse2t64).

Linux — .deb (Debian, Ubuntu)

sudo apt install ./G9BrowserAgent_<version>_amd64.deb

G9BrowserAgent appears in your applications menu; it installs to /opt/G9BrowserAgent, and the command is g9browseragent.

First-time setup

On its first start, G9BrowserAgent opens Setup: five steps, each with Mark as done and Skip, and you can come back to it any time from the sidebar.

1. Browsers — lists the Edge and Chrome G9BrowserAgent found. Install Chrome for Testing downloads the pinned version G9BrowserAgent was tested with (about 200 MB, checked against a known SHA-256). A pinned browser never updates under you, so today's run and next month's run use the same browser. Optional: G9BrowserAgent works with the Edge or Chrome you already have.

2. Automation profile — background runs use their own browser profile, never yours. Open it once, sign in to the app you test, and close the window: later runs start signed in.

3. Background policies (Windows only) — a browser stops drawing a window that is covered, and then quietly drops input. These optional per-user settings keep your own browser drawing, so agents can work in it while you do something else. G9BrowserAgent records the old values first, and Undo restores them. On macOS and Linux there is nothing to set; the step says so.

4. AI clients — registers G9BrowserAgent with the AI clients it finds (Claude Code, Cursor, VS Code, Claude Desktop). It shows the change first, backs up each settings file, and can Remove it again.

5. Browser extension — copies the extension to G9BrowserAgent's data folder and walks you through loading it once (next section).

After Setup, restart your AI client so it loads the new tools.

Add the extension to your browser

This is optional — agents can always use a browser G9BrowserAgent starts — but it is what lets an agent work in your browser, with your logins, and it gives you the side panel.

1. Open edge://extensions (Edge) or chrome://extensions (Chrome).

2. Turn on Developer mode.

3. Click Load unpacked and choose the folder G9BrowserAgent prepared (Setup put the path on your clipboard):

   System	Folder
   Windows	%LOCALAPPDATA%\G9BrowserAgent\extension
   macOS, Linux	~/.g9browseragent/extension
   From the source code	<repository>/extension

4. Pin the G9BrowserAgent icon to the toolbar, and click it to open the side panel.

Leave the folder where it is: the browser knows the extension by its folder. G9BrowserAgent refreshes that folder when it updates, and the extension reloads itself, so you do this only once. (Browsers do not allow extensions outside their store to install themselves; that is why this one step is manual.)

Connect your AI client (MCP)

Setup → AI clients does this for you. To do it by hand, add an MCP server called g9browseragent to your client's settings. From the desktop app, the entry runs G9BrowserAgent's own executable in Node mode:

{
  "mcpServers": {
    "g9browseragent": {
      "command": "C:/Users/<you>/AppData/Local/Programs/G9BrowserAgent/G9BrowserAgent.exe",
      "args": ["C:/Users/<you>/AppData/Local/Programs/G9BrowserAgent/resources/mcp/shim.mjs"],
      "env": { "ELECTRON_RUN_AS_NODE": "1" }
    }
  }
}

Where each client keeps its settings: Claude Code ~/.claude.json (or claude mcp add), Cursor ~/.cursor/mcp.json, VS Code Code/User/mcp.json in your user settings folder (the key there is servers), Claude Desktop Claude/claude_desktop_config.json in the same folder. The side panel's Connect your agent → copy config gives you the entry too.

Restart the AI client afterwards: clients load MCP servers only when they start.

Your first session

1. Open the page you want to test in Edge or Chrome, and open the G9BrowserAgent side panel.

2. Ask your agent, in plain words. For example:

   • "Check this page for problems."

   • "Log in as the test user and confirm the orders list loads."

   • "Why does the Save button do nothing?"

   • "Record a checkout flow on the Demo Shop, and add a check that the order number appears."

3. The agent takes the tab you are looking at, and you watch it work. The panel shows each action as it happens.

No extension? Ask the agent to open a URL: G9BrowserAgent starts a browser in the background and works there. The desktop app's Watch view shows you what it sees.

The Demo Shop used for these pictures is a made-up page in this repository (setup/fixtures/demo-shop.html); node setup/serve.mjs also serves a test page full of deliberate bugs to find.

The side panel

Click the G9BrowserAgent icon in the toolbar. The header always shows the version badge (click it for About), ↗ (open the panel in its own window) and Stop, which immediately blocks every agent action — in this browser and in the daemon — until you press Resume.

Session

• Daemon status, with a coloured dot:

  • Daemon connected (green) — the address, and which engine this browser is (engine-1). A g9d vX pill shows the daemon's version; if it differs from the extension's, a warning says which one to update.

  • Connecting… (amber) — looking for the daemon.

  • Daemon offline — nothing is running yet. That is normal: your AI client starts the daemon when it connects, and the desktop app keeps it running. The extension retries by itself ("next try in N s"); Reconnect now tries at once.

  • Daemon refused this extension / Port taken by a v1 bridge — with the reason and the fix; Try again after fixing it.

  • settings changes the daemon address, if you moved it off port 8765.

• Agents — every connected agent, its project, and the tab it is on (click to bring it forward). Engines lists the browsers G9BrowserAgent is driving.

• Current tab — its title and address, whether console and network are being recorded, and the error / warning / request counts. Record from now starts capturing on this tab before any agent does; tick reload to capture page load to catch problems during loading. Detach all releases every tab.

• Auto-attach — which tabs are captured from their first load: Off, Project sites (the default: the sites in the connected agents' g9.project.json) or All tabs.

• Keep working elsewhere — Pop out tab moves the tab into its own window (keep that window visible), Send to background continues it in a browser G9BrowserAgent starts (the page reloads there with its cookies).

• Input — Direct (instant and exact), Human (the default: curved mouse paths, natural clicks and typing) or Stealth (human input with no scripted shortcuts).

• Connect your agent — the MCP entry to copy. Activity — every agent action, live.

Automation

• Start recording — do the flow yourself; every click, entry and selection is stored with several ways to find the element again.

• Flows — grouped by site, then suite, with filters (site, suite, tag, last verdict, flaky, text). Run N flows replays what the filter shows, one tab at a time (@manual flows are skipped).

• Open a flow for replay, dry run, adding checks, approving its "known world", history, export (a Playwright test or a Git-friendly FlowSpec), and its name, suite and tags.

• Repository — Pull from repo / Push all to repo keep flows in your project's folder.

Issues

• New issue captures the screenshot, address, console, failed requests and the DOM the moment you press it — while the bug is on screen. You write it up afterwards.

• Issues are grouped by site, then Open / Filed / Closed, with severity, age, tracker key and chips for the evidence they hold. Agents can file issues too (browser_issue).

About

The extension's version (and the one before it), the browser, the daemon's version and process, the connection, and this browser's engine id. Copy details puts all of it on the clipboard for a bug report; What's new shows the change notes. After an update, a notice at the top of the panel says so once.

The desktop app

The top bar always shows the daemon's status and Stop all; the tray icon has Stop all and Resume too. The sidebar footer shows the update status.

How an agent drives the browser

Agents get 15 tools. The ones they use most:

The full list, with every argument, is in the technical reference.

Mouse and keyboard. Input goes through the browser's own input pipeline (Chrome DevTools Protocol), not through JavaScript events, so the page sees trusted events. At the default Human level the pointer moves along a curved path with natural speed, a click has a press and a release, wheel scrolling comes in notches, and typing has a rhythm. Direct sends exact, instant input. Stealth adds rules for pages that look for automation. Every run has a seed, so the same seed replays the same motion. Details: docs/HUMANIZE.md.

Hidden tabs. A browser does not deliver mouse input to a tab you cannot see (a background tab or a minimized window). G9BrowserAgent notices, refuses the action instead of pretending, and the side panel offers Pop out or Send to background. Background browsers (Engine 2) are headless and never have this problem — use them for anything unattended.

Sharing. Each tab has one owner; changes on a tab run one at a time; other agents get a clear "owned by" message. Stop blocks everything, and only a person can resume.

Watching a background tab. An agent can open a live view of any tab, headless ones included (browser_tabs action:"watch"): a window in your browser shows the page moving, with the agent's pointer. The side panel's ◉ Live view opens the same view. Details.

A browser on a server

G9BrowserAgent also runs on a server, as a browser node. It is a Docker container:

• A web desktop shows the browser in a page. You watch it, behind a password, and step in for a sign-in.

• Its browser has the extension, and the daemon runs inside the container.

• Agents on other machines connect to it over MCP with a token, for example claude mcp add --transport http ….

Use one container per account. Building, running, nginx in front of it and the security rules are in docker/README.md.

Browser profiles

• Your own profile is used only by the extension, in your own browser. G9BrowserAgent never opens it from outside: Chrome and Edge protect it, and G9BrowserAgent refuses to launch on it.

• Background browsers use G9BrowserAgent's own profiles, in G9_HOME/profiles/<name> (the default one is automation). Sign in there once (Setup step 2, or Warm (open headed) in Engines), and later runs start signed in. A profile keeps its logins on this machine only: browsers encrypt cookies per machine.

• G9BrowserAgent turns off browser sync and sign-in in its profiles, and warns if a profile is signed in to a browser account.

Updates

• Nothing is interrupted: G9BrowserAgent installs only when no run is in progress and no background browser is open, and re-checks every minute until then.

• The extension updates with the app. After an update, G9BrowserAgent refreshes its extension folder and the extension reloads itself once no agent call is in flight. The side panel's badge shows the new version. If it ever does not, press Reload on the extension (or Engines → Update and reload).

Settings → Updates on a Linux install that updates by hand; on Windows and with the AppImage the card also offers the install buttons when a new version is ready.

• Settings → Updates has Check now and the update source: official (the default, nothing to set up), custom (your own https:// folder with the same files), or off.

• Updating from source: git pull, then reload the extension in the browser.

Upgrading from G9 (3.2.0 and earlier)

Until 3.2.0 this app was called G9. It updates to G9BrowserAgent like to any other version, and then takes care of the rename itself:

• AI clients. Their entry moves from g9-browser to g9browseragent and starts the renamed app (each settings file is backed up first). Restart your AI clients once.

• The data folder moves from %LOCALAPPDATA%\G9 (~/.g9 on macOS and Linux) to %LOCALAPPDATA%\G9BrowserAgent (~/.g9browseragent), with your recordings, runs and the background browsers' logins — the first time G9BrowserAgent starts while nothing else is using the folder, usually at your next sign-in. The app then tells you, and reopens Setup → Browser extension: remove the old extension on the extensions page and Load unpacked again from the new folder (a browser knows an extension by its folder).

• Start at sign-in, if you had it on, keeps working.

• Windows: the app stays in the folder it was installed to (%LOCALAPPDATA%\Programs\G9), now as G9BrowserAgent.exe; a new install goes to %LOCALAPPDATA%\Programs\G9BrowserAgent.

• macOS: drag G9BrowserAgent into Applications and delete the old G9 app.

• Debian/Ubuntu: sudo apt install ./G9BrowserAgent_<version>_amd64.deb replaces the g9-desktop package.

Troubleshooting

More, with the causes: technical reference → Troubleshooting. G9BrowserAgent's logs are in G9_HOME/logs (daemon.log, desktop.log, install.log).

Uninstall and reset

Undo what G9BrowserAgent changed outside its own folders first, while G9BrowserAgent is still installed:

1. Setup → Background policies → Undo (Windows, only if you applied them).

2. Setup → AI clients → Remove for each client.

3. Settings → turn off Start G9BrowserAgent when I sign in.

4. Remove the G9BrowserAgent extension on your browser's extensions page.

5. Engines → Stop any running browser, then Settings → Shut down daemon.

Then remove the app:

• Windows: Settings → Apps → G9BrowserAgent → Uninstall.

• macOS: drag G9BrowserAgent from Applications to the Trash.

• Linux AppImage: delete the file (and ~/.config/autostart/g9browseragent.desktop, if you enabled start at sign-in).

• Linux .deb: sudo apt remove g9browseragent.

Your data stays, on purpose — delete it by hand when you are sure (it holds your recordings, run evidence and the background browsers' logins):

To reset G9BrowserAgent without uninstalling it: shut down the daemon (step 5), then delete or rename G9_HOME. The next start is a fresh install, and Setup runs again.

For developers

G9BrowserAgent's core is plain Node.js with no npm dependencies; only the desktop app (Electron) has any.

git clone https://github.com/ImanKari/G9BrowserAgent.git
cd G9BrowserAgent
npm test                    # unit tests, self-test and extension suite (Node 22+)
node setup/check.mjs        # only the checks your change needs

• Use it from source: point your MCP client at node <repo>/mcp/shim.mjs, and load <repo>/extension unpacked. On Windows, setup\install.ps1 checks Node, runs the tests, and writes the MCP config for you. There is no service to start; npm run daemon runs the daemon in the foreground with its log on screen.

• The desktop app from source: cd desktop && npm ci && npm start.

• Build the packages: cd desktop && npm run build:win (or build:mac, build:linux) — each on its own system. The output, with its latest*.yml update metadata, is in desktop/dist, and npm run verify:artifacts checks every file against it.

• Test the update end to end: node desktop/test/update-e2e.mjs --old <older build> --new desktop/dist installs the older build, serves the new one from a local feed, and walks through download, corruption, interruption, skip, busy daemon, install on quit, restart and the extension refresh.

Development vs. installed:

Releases come from the Azure DevOps pipeline (azure-pipelines.yml), the source of truth: it runs every offline check on Windows and the portable suites on Linux and macOS, builds the packages on each system, runs the real update test on each, verifies every file, and only then — from main — tags the version, mirrors the repository to GitHub and publishes the GitHub Release.

Before changing the code, read AIGuide.md (design decisions and the change log) and the technical reference. Every change is recorded in AIGuide.md and bumps the version.

More documentation: technical reference · operator guide · architecture · daemon protocol · human input · stealth · desktop app · engine

Security and privacy

G9BrowserAgent gives agents full control of the browser tabs they use — every page, cookie and login in that browser. Treat it like an SSH key, and use it on machines whose users and software you trust.

• Local only. The daemon listens on 127.0.0.1, never on your network. Web pages are refused: a page cannot connect to it, even one served from your own machine.

• No token. Any program running as a user on this machine can connect to the daemon. That is a deliberate choice for a trusted QA machine. The one way in from another machine is the MCP endpoint over HTTP (A browser on a server). It will not listen beyond loopback without a long bearer token.

• Nothing leaves your machine. No telemetry, no accounts. Recordings, issues and evidence stay in G9_HOME and in the extension's storage. The only outside connections are the pages you test, the update check (GitHub) and, if you choose it, the Chrome for Testing download (Google).

• Background browsers are separate. They never open your profile, have sync turned off, and are driven over a pipe (no debugging port is open).

• Stop is always there, and agents cannot undo it.

• While the extension controls a tab, the browser shows "started debugging this browser". That bar is the browser's own warning and cannot be hidden.

• The packages are not code-signed yet. Check the SHA-256 in the release notes if in doubt.

Details: technical reference → Security and trust model.

Known limitations

• Unsigned packages. Windows SmartScreen and macOS Gatekeeper ask once. macOS updates are installed by hand, and so are .deb updates (G9BrowserAgent tells you when one is out).

• Measured on Windows. The detailed measurements (window states, timing, stealth) were taken on Windows 11. On macOS and Linux the automated suites and the update test run on every release, but the long live measurements were not repeated.

• Windows-only extras. The background policies that keep your own browser drawing when covered exist on Windows only. Everywhere, a minimized window or a background tab stops receiving input — use a background browser (headless) for unattended work.

• x64 only on Windows and Linux (no ARM builds there); macOS has both Apple silicon and Intel.

• Edge and Chrome only. No Firefox or Safari. Device emulation is not a real device.

• Headless can be detected by determined bot detectors; stealth reduces what G9BrowserAgent adds, but a headless browser still differs from a visible one.

• Browser pages you cannot control: chrome:// / edge:// pages, the web stores, and native dialogs (print, the file picker — use upload instead).

• Updating while an AI client is using G9BrowserAgent may end that client's G9BrowserAgent tools until its next call.

• Not measured at all: a locked screen, another virtual desktop, display scaling above 100%, runs longer than 10 minutes.

The complete list: technical reference → Limits and known gaps.

License

MIT © Iman Kari