Why this exists

AI browsers all take the same shape: you install a new browser with an assistant
inside — Aside, Comet, Dia. That shape costs you three things:

We took the opposite arrangement. No new browser — your existing Chrome, your
existing logins, and the assistant works in the window you're already looking at.
You watch every click land and can take the mouse back mid-task. Nothing to migrate,
nothing to hand over.

That choice is also why this runs on Windows, macOS, Linux and WSL: we didn't have to
build a browser for each one, so there was no platform to pick.

Need something? Build it.

That's the whole idea. Not a product waiting on someone else's roadmap —
a small tool you own, on the machine you already use, in the browser you're
already logged into. About 2,600 lines of JavaScript, Python and shell — small enough to read
in an afternoon. Read it, change it, make it yours.

Wbrowser targets Windows, macOS, Linux, and WSL — because "which OS are you on?"
should never be the reason you can't automate your own browser.
Measured on macOS, native Linux, WSL2 and Windows-native — though not every check ran
on every platform (see Platform notes).

What is this?

Most automation tools give your AI a fresh, empty browser. So it can't see your email,
your dashboards, or anything behind a login — unless you hand over passwords or set up
API integrations for every single service.

Wbrowser takes the opposite approach: you log in once, by hand, in a normal Chrome window.
After that, your terminal (or your AI assistant) can drive that exact window — already
logged in, everywhere.

./wb go https://mail.example.com   # opens in YOUR logged-in session
./wb read                          # tells you what's on screen
./wb click '#compose'              # clicks it

Wbrowser never sees your passwords. You type them; Chrome stores them; Wbrowser
just drives the window that's already open.

One login often unlocks many sites

This is the part that makes it worth the setup. Log into Google once in that window and:

Google itself       google.com · youtube.com · your Workspace apps
Sites using Google SSO   your CRM, your booking system, your dashboards —
                         whatever "Sign in with Google" reaches
Everything else     log in by hand once; it stays

Measured on a real profile: one Google sign-in brought along YouTube and two
internal business systems that use Google SSO — none of which were logged into
separately. The rest (GitHub, Reddit, a bank-like portal) were signed into by hand
once and have persisted since.

So the setup cost is roughly: one Google login, plus one login each for whatever
doesn't use Google. After that your agent reaches all of it.

🔴 The flip side is the same fact: whoever can drive this browser can act on every
one of those sites. See Security.

What it won't do

• Ask for or store your password. You sign in; Chrome keeps it; Wbrowser drives
  the window that's already open. type never logs what was typed.
• Print cookie values. Not in output, not in logs — cookies are the login.
• Guess which account you meant. Name an account that isn't open and it fails.
  Sending mail from the wrong account is worse than an error message.
• Click submit / pay / delete on a schedule. Unattended jobs refuse those steps
  unless that specific job opts in. Nobody is watching when a cron job goes wrong.

One limit we measured and are telling you about

Chrome's debugging port has no authentication. Any process running as you on that
machine can attach and drive your sessions — we verified this by connecting from an
unrelated process and listing the open tabs. 127.0.0.1 is not a fence; it means
"anything running as you gets in".

That is Chrome's design, not something we added, and every tool in this category
inherits it. We'd rather write it down than let you find out later —
see Security for the full threat model.

Quick start

git clone https://github.com/<you>/Wbrowser.git
cd Wbrowser
# Wbrowser drives your *system* Chrome, so Playwright's own browser
# download is unnecessary — skip it and save ~400MB:
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install

node launch.js       # 1. opens a dedicated Chrome window
                     # 2. log into your sites in that window (by hand!)
node engine.js       # 3. start the control engine
./wb go https://example.com

That's it. Step 2 is the only thing you ever do manually.

If ./wb says "Permission denied" — the executable bit didn't survive the
clone (some setups strip it). Fix it once:

chmod +x wb install.sh autostart.sh sync-session.sh

Headless servers (no display): Wbrowser detects a missing $DISPLAY and
launches Chrome headless automatically. Force it either way with
WBROWSER_HEADLESS=1 or =0. Note you can't log in by hand without a screen —
use ./sync-session.sh import to bring sessions over from a desktop machine.

Windows users: run these inside WSL, or use node directly on Windows —
both work. See Platform notes.

Why a separate Chrome window?

Since Chrome 136 (March 2025), --remote-debugging-port is ignored for
Chrome's default profile directory. Google made this change because attackers were
using remote debugging to steal cookies.

So a non-default --user-data-dir is now mandatory. Wbrowser creates one at
~/.wbrowser and launches Chrome there.

This means your existing logins do not carry over. You log in once in the new
window, and they persist there from then on.

⚠️ Copying your Chrome profile folder does not work. We tried: 685 cookies
became 3, and every session cookie was dropped. Chrome invalidates profiles it
doesn't recognize. Log in fresh — it takes a minute and it actually works.

Commands

./wb go <url>              open a page, return its structure
./wb read                  summarize the current page
./wb click <selector>      click an element
./wb type <selector> <text>   fill an input
./wb press <key>           Enter, Tab, Escape, ArrowDown…
./wb eval '<js>'           run JavaScript in the page
./wb console [regex]       console logs + uncaught exceptions
./wb network               failed requests (4xx/5xx, CORS, timeouts)
./wb shot [file.png]       screenshot
./wb tabs                  open tabs, grouped by agent
./wb close                 close only the tabs you opened
./wb status                is everything up? which profile?
./wb show                  bring the browser window to the front

Don't guess selectors

./wb read returns the actual clickable elements on the page:

inputs(1):
  - #searchbox_input  (Search the web without being tracked)
buttons(3): Search, Sign in, Settings

Copy from there. (We once guessed input[name=q] for a search box — it was a
textarea. read had the right answer all along.)

Just tell your assistant what to do

Once connected, you stop typing commands and start describing outcomes:

"Open my dashboard and summarise today's numbers."
"What's in my cart on that shopping site?"
"Check whether that booking actually went through."

The connection uses the Model Context Protocol —
if your assistant supports MCP (Claude, Cursor, and others do), this is a few lines
of config and you're done.

Local (stdio):

{
  "mcpServers": {
    "wbrowser": {
      "command": "node",
      "args": ["/path/to/Wbrowser/mcp-server.js"]
    }
  }
}

Remote (HTTP):

export WBROWSER_MCP_TOKEN=$(openssl rand -hex 32)
node mcp-server.js --http --port 7982 --host 127.0.0.1

Then just talk to your assistant:

"Open my dashboard and summarize today's numbers."
"What's in my cart on that shopping site?"

Tools: browser_open browser_read browser_click browser_type browser_press
browser_eval browser_console browser_screenshot browser_tabs browser_status

🔴 The remote server refuses to start without a token. This isn't optional —
it drives a browser holding all your logins. Anyone who reaches that port becomes you.

What an agent should know before driving

These came from actual mistakes made while building this. If you write your own
skill/prompt around Wbrowser, put them in it:

1. Don't guess selectors. browser_read returns the real ones on the page.
   We guessed input[name=q] for a search box; it was a textarea, and read
   had said so all along.
2. Read the form back before submitting. In one batch form, rows 2-10 had empty
   customer fields because the "keep" checkboxes didn't cover them. Reading every row
   before clicking caught it; clicking first would have created 9 broken records.
3. Count as you repeat. Sending 8 Enter presses in a row produced 40 rows — the
   page handled them faster than expected. Press once, count, stop at the target.
4. eval beats type for framework forms; type beats eval when that fails.
   React ignores direct value assignment — use the native setter plus input/change
   events. If it still doesn't take, browser_type sends real keystrokes.
5. Check what you're attached to. browser_status tells you whether the window
   actually holds logins. An empty profile answers every command successfully while
   doing nothing useful.

Scheduled jobs (cron)

Create jobs/morning-check.json:

{
  "schedule": "0 9 * * 1-5",
  "tab": "morning",
  "steps": [
    { "goto": "https://dashboard.example.com", "wait": 2000 },
    { "eval": "document.querySelector('.total').innerText" },
    { "shot": true }
  ]
}

node cron.js list      # what's registered
node cron.js next      # when each job runs next
node cron.js run <name>   # run once, now
node cron.js daemon    # run on schedule

0 9 * * 1-5 = minute 0, hour 9, weekdays. Standard 5-field cron.

Irreversible actions are blocked by default

Unattended automation means nobody is watching when it goes wrong. So steps that
look like submit / payment / delete are refused:

⛔ step 2 blocked — looks irreversible (click: #submit-payment)
   If you meant it, add "allowIrreversible": true to the job file.

You opt in per job, not globally.

Who's driving? (visual indicator)

When an agent is controlling the browser, you see it:

• A translucent border around the page, with a label: 🤖 my-agent in control
• The tab title gets prefixed: [my-agent] Dashboard

The border fades after 6 seconds of inactivity, so "in control" actually means
right now. Colors are derived from the agent name, so multiple agents are
distinguishable at a glance.

The tab prefix survives navigation — a MutationObserver re-applies it whenever
the page rewrites its own title (which SPAs do constantly).

Multiple accounts

Open several Chrome profiles in the same window (Chrome's profile switcher), and
Wbrowser can target them individually:

./wb -a [email protected] go https://mail.example.com
./wb windows                    # list open profiles

Or map sites to accounts in accounts.json:

{
  "sites": {
    "mail.example.com": { "account": "[email protected]" }
  }
}

🔴 If you name an account that isn't open, Wbrowser fails instead of guessing.
Sending mail from the wrong account is worse than an error message.

Platform notes

Override with WBROWSER_CHROME=/path/to/chrome if detection fails.

Tested on real hardware (2026-08-24):

Platform	Chrome	Verified by	What was measured there
macOS 15	151	separate operator	launch · engine · CLI · state paths
Linux (native, headless)	148	separate operator	the above + security review
WSL2 + Windows Chrome	151	maintainer	the above
Windows 10 (native)	151	separate operator	the above + end-to-end

Not every check ran on every platform. The security review (no-token MCP refusal
confirmed with ss, engine unreachable off-loopback) was done on Linux. The
end-to-end run (/health → /act → real page extraction) was done on Windows.
UNC paths (\\wsl.localhost\...) also work — measured, contrary to our expectation.

The security review was done on Linux, on a different machine: with no token the MCP HTTP server
exits and never opens a socket (verified with ss); the engine binds to
127.0.0.1 only and is unreachable over the tailnet.

Security

This tool drives a browser that holds all your logins. Treat it accordingly.

• 🔴 127.0.0.1 is not a fence — it is "any process running as you gets in."
  The Chrome debugging port (9222) has no authentication. Any local process on that
  machine — another app, an npm postinstall hook, a stray script — can attach and drive
  every session you are logged into. Measured: an unrelated process reached
  GET http://127.0.0.1:9222/json/list and enumerated the open tabs with no credentials.
  Only run this on a machine where you trust everything that runs as your user.
• The engine binds to 127.0.0.1 only. Never expose it directly.
• 🔴 mcp-server.js --host 0.0.0.0 exists and will bind to every interface. The code
  prints a warning, but by then the port is already open. Use 127.0.0.1 unless you are
  on a trusted private network (VPN/tailnet), and always with a token.
• The MCP HTTP server requires a token and refuses to start without one.
• ./wb type does not log what was typed — it might be a password.
• Cookie values are never printed, logged, or returned by any command.
• Do not use this to enter passwords, card numbers, or government IDs.
  Log in by hand; Wbrowser reuses the session.

Session backup

./sync-session.sh export   # cookies → encrypted store
./sync-session.sh import   # restore on another machine
./sync-session.sh status

🔴 Cookies are as sensitive as passwords — they are the login. The script
refuses to write unless the destination is actually encrypted, and refuses to
restore from ciphertext it can't decrypt.

Environment variables

Run on boot

# Linux / WSL (systemd user service)
./install.sh
systemctl --user status wbrowser

The engine starts automatically. The browser still needs launching — it's a
desktop process, and it should be your choice when it opens.

Known limitations

• No automated test suite. CI checks syntax and a few invariants; everything that
  touches a real browser was measured by hand across four platforms. That does not
  scale, and it is the most useful thing a contributor could add.

• No natural-language loop built in. The agent picks selectors; read gives it
  the real ones, so it doesn't have to guess.

• Chrome/Chromium only. Firefox has no CDP.

• One CDP port = one Chrome process. Profiles opened from within that window are
  visible; a separately-launched Chrome is not.

Contributing & security

• CONTRIBUTING.md — the rules that shaped this code, and how to test it
• SECURITY.md — 🔴 the threat model. Read it before running this on a
  shared machine: the Chrome debugging port has no authentication, so any local
  process running as you can drive your sessions.

Found a security problem? Please open a
private advisory
rather than a public issue.

License

MIT — see LICENSE.