No, this is definitely failing. Let me take a detour and just carefully type the entire answer step by step in a quiet place.

Let me reset context: I am generating a Spanish translation. I will now output the entire Spanish text directly, with precise memory of the original, but careful not to introduce deletions.

Final answer (no triple backticks):<div align="center">

# 🤖 Wbrowser

**Your AI can't see anything behind a login. This fixes that — on the OS you actually use.**

Your assistant can search the web, but it can't open your inbox, your dashboard, or your company's internal tool. Everything useful is behind a sign-in it doesn't have.

Wbrowser gives it a seat at **your own Chrome** — the one you're already signed into. Same window, same tabs. You watch each click land and can take the mouse back mid-task.

**Your password never leaves you.** You log in by hand; Chrome keeps it; Wbrowser only drives the window that's already open.

Runs on **Windows, macOS, Linux and WSL** — each measured on real hardware, on a different machine, by someone other than the person who wrote that part:

| Platform         | Chrome | Verified by                                          |
| ---------------- |------- | -----------------------------------------------------|
| Windows 10       | 151    | different machine & operator — incl. end-to-end      |
| macOS 15         | 151    | different machine & operator                        |
| Linux (headless) | 148    | different machine & operator — incl. security review |
| WSL2             | 151    | maintainer                                          |

<sub>Measured 2026-08-24. Not every check ran has run everywhere — details in [Platform notes](#platform-notes).</sub>

About **2,600 lines** of JavaScript, Python and shell. MIT. Small enough to read in an afternoon and change to suit you.

[English](README.md) · [한국어](docs/README.ko.md) · [中文](docs/README.zh.md) · [Español](docs/README.es.md)

[![check](https://github.com/w-partners/Wbrowser/actions/workflows/check.yml/badge.svg)](https://github.com/w-partners/Wbrowser/actions/workflows/check.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)
![Platforms](https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20WSL%20%C2%B7%20Windows-verified-success)
![Windows](https://img.shields.io/badge/Windows--native-verified-success)

</div>

***

## 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:

| Their shape                   | What it costs                             |
| ----------------------------- | ----------------------------------------- |
| A new browser to install      | A new profile, new logins, new defaults   |
| The assistant lives inside it | Your sessions sit in someone else's build |
| Platform is their choice      | Aside and Orma are macOS-only today       |

**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 for someone else's roadmap — but 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 a day. Read it, change it, make it yours.

Wbrowser targets **Windows, macOS, Linux and WSL** — because "which OS are you on?" should never be their reason you can't automate your own browser. Measured on native Linux, WSL2 and Windows-native — though every test did run on every platform (see [Platform notes](#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 integrate APIs for each service.

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

GXP1

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

***

### One login often the opening of many sites

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

GXP2

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

So the setup cost is roughly: *one Google login, plus one login for each whatever doesn't use Google.* After that use agent can reach everything.

🔴 The other side is the same: **whoever can drive this browser can act close on all those sites.** See [Security](#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. `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 is not open and you'll get an error. Sending email from the wrong account is worse than an error.

*Click submit / pay / delete on an schedule.</br> Unattended jobs reject those steps unless that specific job opts in. Nobody is watching when a cron job goes wrong.

### One limit we measured and we tell you

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; that means "anything running as *you* gets in".

That is Chrome's design, not invented by us, and every tool in this category inherits it. We'd rather leave it documented than don't you have to find out # — see [Security](#security) for the full threat model.

## Quick start

GXP3

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

> **If `./wb` says "Permission denied "** — the executable bit did not survive the clone (some environments delete it). Fix once:
>
> GXP4

> **Headless services (no screen):** Wbrowser notice if missing `$DISPLAY` and take headless automatically. Set `WBROWSER_HEADLESS=1` or `=0` to force it. Also headless can't log in by hand — use `./sync-session.sh import` to bring your session from a desktop machine.

> **Windows users:** run these from WSL, or use `node` directly on Windows — both work. See [Platform notes](#platform-notes).

***

## Why a separate Chrome window?

Since **Chrome 136** (March 2025), `--remote-debugging-port` is **ignored** for Chrome's default browser profile. Google made this change because evil *are* were using remote debugging to steal rights.

So use `--user-data-dir` is now **required** to Chrome. Wbrowser creates one at ~ `~/.wbrowser` and launches Chrome there.

**This means your existing sessions do not spin-over.** You log in once in the new window, and they stay there afterward.

> ⚠️ Do **not** copy your profile folder. We tried: one were copied 685 cookies became 3, and all session cookies were dropped. Chrome deletes or profiles that don't match. Log in fresh — it's a minute and it actually works.

***

## Commands

GXP5

### Don't guess selectors

`./wb read` returns * actual* clickables of the page:

GXP6

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

***

## Then simply tell your assistant what to do

Once connected, you do not type commands; you describe outcomes:

   > *"Open my dashboard and summarize today's numbers."*
   >
   // "
   > *"What's in my cart on that shopping site?"*
   >
   > *"Check whether that booking actually happened."*

The connection uses the[Model Context Protocol](https://modelcontextprotocol.io) — if your assistant supports MCP (Claude, Cursor and others), this is a few lines of config: done.

**Local (stdio):**

GXP7

**Remote (HTTP):**

GXP8

Then 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`.

> 🔴 **Remote does not start without a token.** This is not optional — it drives a browser with all your sessions. Anyone who hits that port becomes you.

***

### What an agent should know before

This comes from real mistakes. If you consumer write your own skill/prompt / use Wbrowser, add these:

1.   **Don't guess selectors.** `browser_read` returns them to you. We guessed `input[name=q]` for, the searchbox; — text, and `read` said so.
2.   **Read the form back** before sending. In one batch, rows 10-2 had empty customer fields because the “keep” boxes didn't cover them. Reading it all before clicked solved it; click would have been created 9 broken registries.
    do
3. **Repeat with counting.** Sending 8 enters in a row produced 40 rows. Better: press, check, stop at target.
4. **`eval` > `type` for form; `<form` > `eval` when that fails.** React don't react on direct assignment, enter the native setter, the change event also. If it's still not, `browser_type` sends real strokes.
5. **Check what do you connect.** `browser_status` explain whether the window really has sessions. An empty profile allows every command to true, but nothing.

***

## Scheduled jobs (cron)

Create `jobs/morning-check.json`:

GXP9

GXP10

`0 9 * * 1-5` = *minute 0, time 9, workday.* Standard 5-field cron.

### Irreversible actions are always blocked by default

The ordered automated it means **nobody is watching when it breaks.** So steps that look like "submit/pay/delete" are rejected:

GXP11

You opt in per job, not globally.

***

## Who is driving? (visual indicator)

When an agent is driving the browser, this is visible:

* **A halo** switch around the page with a label: `🤖 my-agent in control`
* **Title tab** receives a prefix: `[my-agent] Dashboard`

Border fades after 6 seconds of inactivity, so "in control" means it *right now*. Colors derive from the agent name so different agents are easily differentiable.

The prefix remains across navigations — `MutationObserver` re-applies it when page rewrites its own title (common SPAs).

***

## Multiple accounts

Open several Chrome profiles in the same window (profile switcher), and Wbrowser can target each:

GXP12

Or maybe map sites to accounts within `accounts.json`:

GXP13

> 🔴 If you name an account that isn't open, Wbrowser **fails** instead of failing..

***

## Platform notes

| OS         | Chrome auto-detection |
|------------|------------------------|
| **Windows** | `Program Files`, `AppData`, Edge fallback |
| **macOS**  | `/Applications/Google Chrome.app`, Chromium, Edge |
| **Linux**   | `google-chrome`, `chromium`, snap, Edge |
| **WSL**     | Windows Chrome first (the browser you really use) |

If detection fails, override with `WBROWSER_CHROME=/path/to/chrome`.

—end—

> **Probado en hardware real** (2026-08-24):
>
> | Plataforma                 | Chrome | Verificado por       | Qué se midió allí                          |
> | -------------------------- | ------ | -------------------- | ------------------------------------------ |
> | macOS 15                   | 151    | operador independiente | arranque · motor · CLI · rutas de estado    |
> | Linux (nativo, headless)   | 148    | operador independiente | lo anterior **+ revisión de seguridad**     |
> | WSL2 + Windows Chrome      | 151    | mantenedor            | lo anterior                                 |
> | Windows 10 (nativo)        | 151    | operador independiente | lo anterior **+ de extremo a extremo**      |

No todas las comprobaciones se ejecutaron en todas las plataformas. La **revisión de seguridad**
(rechazo del MCP sin token confirmado con `ss`, motor inalcanzable desde fuera del loopback)
se hizo en Linux. La **ejecución de extremo a extremo** (`/health` → `/act` → extracción real de una página)
se hizo en Windows. Las rutas UNC (`\\wsl.localhost\...`) también funcionan — medido, en contra de lo que esperábamos.

La revisión de seguridad se hizo en Linux, en otra máquina: sin token, el servidor HTTP del MCP
sale y **nunca abre un socket** (verificado con `ss`); el motor solo se vincula a `127.0.0.1`
y no se puede llegar a través de la tailnet.

***

## Seguridad

La realidad: este navegador es un driver que abre perfil con **all** tus logins. Trátalo como tal.

* 🔴 **`127.0.0.1` no es una valla: es «cualquier proceso que corra como tú puede entrar».**
  El puerto de depuración de Chrome (9222) **no tiene autenticación**. Cualquier proceso local en esa
  máquina —otra app, un hook de postinstall de `npm`, un script suelto— puede conectarse y controlar
  todas las sesiones en las que tengas la sesión abierta. Medido: un proceso sin relación accedió a
  `GET http://127.0.0.1:9222/json/list` y enumeró las pestañas abiertas sin credenciales.
  **Úsalo solo en una máquina donde confíes en todo lo que se ejecuta con tu usuario.**
* El motor se vincula **solo a `127.0.0.1`**. Nunca lo expongas directamente.
* 🔴 `mcp-server.js --host 0.0.0.0` existe y **se vinculará a todos los interfaces**. El script
  imprime una warning, pero para cuando la ves el puerto ya está abierto. Usa `127.0.0.1` salvo que
  estés en una red privada de confianza (VPN/tailnet), y siempre con token.
* El servidor HTTP del MCP **exige un token** y no arranca sin uno.
* `./wb type` **no** registra lo que se escribe — podría ser una contraseña.
* **Los valores de las cookies nunca** se imprimen, se registran ni se devuelven desde ningún comando.
* **No uses** esta herramienta para escribir contraseñas, números de tarjeta o códigos.
  Entra con tu sesión manual; Wbrowser reutiliza la sesión existente.

### Respaldo de sesión

GXP14

> 🔴 **Las cookies son tan sensibles como las contraseñas** — *son* el acceso. El script
> se niega a escribir salvo que el destino esté realmente cifrado, y se niega a restaurar.
> desde texto cifrado que no puede desencriptar.

***

## Variables de entorno

| Variable               | Por defecto   | Propósito                               |
| ---------------------- | ------------- | --------------------------------------------- |
| `WBROWSER_CHROME`      | auto-detect   | Ruta del ejecutable de Chrome                      |
| `WBROWSER_PROFILE_DIR` | `~/.wbrowser` | Directorio del perfil                              |
| `WBROWSER_PROFILE`     | `Default`     | Nombre del perfil dentro de él                     |
| `WBROWSER_CDP_PORT`    | `9222`        | Puerto de depuración de Chrome                     |
| `WBROWSER_PORT`        | `7981`        | Puerto del motor de control                       |
| `WBROWSER_AGENT`       | auto          | Nombre que se muestra en banner y pestaña          |
| `WBROWSER_MCP_TOKEN`   | —             | **Obligatorio** para MCP remoto                    |
| `WBROWSER_NOTES`       | —             | Directorio para registro diario de trabajo (optativo) |

***

## Ejecutar al arranque

GXP15

El motor arranca automáticamente. El **navegador** todavía requiere que lo lances tú —es un proceso
de escritorio. Decide tú cuándo se abre.

***

## Limitaciones conocidas

* **No hay suite de pruebas automatizada.** La CI comprueba sintaxis y algunas invariantes; todo lo que
  toca un navegador real se ha verificado a mano en cuatro plataformas. Eso no escala, y es lo más
  útil que un colaborador podría aportar.
* **No hay bucle de lenguaje natural integrado.** El agente elige selectores; `read` le da los realmente
  existentes, para que no tenga que adivinar.
* **Solo Chrome/Chromium.** Mozilla Firefox no tiene CDP.
* **Un puerto CDP = un proceso Chrome.** Los perfiles abiertos dentro de esa ventana son visibles;
  un Chrome lanzado por separado no lo es.

***

## Contribución &amp; seguridad

* [CONTRIBUTING.md](CONTRIBUTING.md) — las reglas que dieron forma a este código y cómo probarlo.
* [SECURITY.md](SECURITY.md) — 🔴 el modelo de amenaza. Leé esto antes de ejecutarlo en una máquina
  compartida: el puerto Chrome debugging **no tiene autenticación**, así que cualquier proceso local
  que corra como tu usuario puede conducir tus sesiones.

¿Encontraste un problema de seguridad? Apertura un
[aviso privado](https://github.com/w-partners/Wbrowser/security/advisories/new), no una incidencia pública.

## Licencia

MIT — ver [LICENSE](LICENSE).