nexus-browser 2.9.0__tar.gz

nexus_browser-2.9.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.log
+.venv/
+
+# Windows / OS
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+.DS_Store
+
+# Backups
+*.bak
+*.tmp
+
+# Development caches (normally stored outside OneDrive by test.ps1)
+.pytest_cache/
+.ruff_cache/

nexus_browser-2.9.0/CHANGELOG.md

@@ -0,0 +1,284 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- PyPI package `nexus-browser` (the MCP server, command `nexus-browser`): the wheel mirrors `client/` and
+  `native-host/` unchanged under `nexus_browser/` (hatchling force-include); `install.ps1` and the three agents keep
+  running from the repository (`[tool.uv] package = false`). Published by Trusted Publishing
+  (`.github/workflows/publish.yml`), checked from the built wheel (initialize, 47 tools).
+- README: animated demo recorded from the real tool; install from PyPI.
+
+### Changed
+- Bridge not reachable and no token: the error now points to the one-time install (install.ps1).
+
+## [Unreleased]
+
+### Added
+
+- `SECURITY.md`: private vulnerability reporting.
+
+### Changed
+
+- Repository renamed to `pironjulien/NexusBrowser`; GitHub redirects the old address.
+
+## [2.9.0] - 2026-10-18 — Secrets masked in images and console logs
+
+Re-run `install.ps1`, then RELOAD the extension (capabilities `capture-field-masking` and `console-masking`
+advertised by ping).
+
+### Security
+- Screenshots, PDFs and Set-of-Mark captures no longer show a password revealed by a "show" button, a card number or
+  a code: before `Page.captureScreenshot` / `Page.printToPDF` (also through `browser_cdp_send`), sensitive fields of
+  every frame (shadow DOM, same-origin and cross-origin iframes) get `-webkit-text-security: disc`, and their own
+  inline style is put back right after. A capture whose page cannot be masked (dialog open) is refused. Checked in
+  the real Chrome (`test.ps1 -Full`): two values of the same length give the same image, the same field shown as an
+  ordinary field gives a different one (screenshot, PDF, cross-origin iframe).
+- Sensitive fields are also recognized by name or id, camelCase included: `cardNumber`, `cc_number`, `cardCvc`,
+  `otp`, `pin`, `securityCode`, `iban`... (`cc` alone, `spinner`, `passenger`, `option` are not secrets).
+- `browser_logs` masks console messages like network bodies: secret keys, URL parameters, object previews
+  (`{name, value}`), tokens quoted in a text (`Bearer …`, `ghp_…`, JWT).
+- Network log: card number, card code, one-time code, PIN and IBAN keys masked in bodies and URL parameters.
+- `NEXUS_CHROME_EXTRA_ARGS` is now an allowlist (`--lang`, `--accept-lang`, `--variations-override-country`,
+  `--disable-features` with `Glic*` features only, `--force-dark-mode`): the former blocklist let through flags that
+  weaken Chrome (`--disable-web-security`, `--disable-features=IsolateOrigins`...).
+
+### Fixed
+- Element screenshots (`selector`, `mark`) were blank when Chrome's page zoom is not 100% (seen at 90%): the clip is
+  now converted with the page zoom reported by `Page.getLayoutMetrics`.
+
+### Added
+- Real Chrome test of masking in a cross-origin iframe (reads and capture).
+- Real Chrome check that Julien's tabs are left intact now ignores tabs of other agents (they may close theirs during
+  the run).
+
+- Every MCP tool has a readable `title` in its annotations, next to its four hints.
+- Startup test: the MCP server answers `initialize` and `tools/list` with no Chrome, bridge or extension, on Windows
+  and on Linux (as MCP directories such as Glama check it); outside Windows the emergency stop keeps watching its
+  file and skips the global hotkey.
+- GitHub Actions: `test.ps1` on Windows and the startup test on Linux, with a Tests badge; `glama.json`.
+- README: Privacy section.
+
+### Changed
+- Published as NexusBrowser in the public repository `pironjulien/chrome-computer-use` (formerly
+  `antigravity-chrome-sidepanel`, then `antigravity-browser-use`; GitHub redirects the old URLs). README rewritten in
+  English for public use.
+
+## [2.8.1] - 2026-10-18 — Screenshots of background tabs no longer freeze
+
+Re-run `install.ps1`, then RELOAD the extension (capability `capture-screencast` advertised by ping).
+
+### Fixed
+- `browser_screenshot` and `browser_vision_inspect` froze for 12 to 20 s (bridge timeout) in a background tab:
+  Chrome stops drawing frames for a hidden tab, so `Page.captureScreenshot` waited after any scroll or change.
+  Measured on the real Chrome (October 18, 20 captures alternating with scrolls): 11 to 13 freezes out of 20 for the
+  plain capture, `Emulation.setFocusEmulationEnabled` and `captureBeyondViewport` (still 7/12), forcing the device
+  metrics (7/12); `fromSurface: false` is refused by Chrome ("Only screenshots from surface are allowed"). A tiny
+  `Page.startScreencast` (16×16, never read) held only for the duration of the capture keeps the renderer drawing:
+  0 freezes out of 40, about 0.1 s per capture, correct image of the scrolled view; the tab stays in the background.
+  If Chrome refuses the screencast, the capture runs as before; it is always stopped, even when the capture fails.
+
+### Changed
+- Chrome relaunch (`launch_chrome`): only `--profile-directory=Default` by default. Extra flags are opt-in
+  through the `NEXUS_CHROME_EXTRA_ARGS` environment variable (`--name` or `--name=value` separated by spaces);
+  anything else, and flags that load or run code (`--load-extension`, `--remote-debugging-*`, command prefixes,
+  `--user-data-dir`, `--no-sandbox`...), are ignored.
+- Agent guide and docstrings: repository-relative paths instead of the author's folders.
+
+### Removed
+- Live validation: the 3 retries of `browser_vision_inspect` (`gels_de_capture`) are gone, a single capture is
+  expected to succeed.
+
+## [2.8.0] - 2026-10-18 — October 18 audit: masked passwords, corrected cookie promise, MCP SDK 2
+
+Re-run `install.ps1` (with Antigravity closed), then RELOAD the extension in `chrome://extensions` (capabilities
+`sensitive-field-masking`, `cdp-reload-no-script` and `ax-value-masking` advertised by ping), then open a new
+conversation in each agent.
+
+### Security
+- Plaintext passwords (severe): `browser_content` (default interactive mode), `browser_vision_inspect`,
+  `browser_find` and the read-back of `browser_fill` returned field values, passwords included; `browser_axtree`
+  returned card numbers and codes (Chrome only masks passwords there, observed in a real run). The value is never
+  returned for a `type=password` field or one whose `autocomplete` is current-password, new-password,
+  one-time-code, cc-number, cc-csc or cc-exp (including a "show password" field switched to `type=text`):
+  `[valeur masquée]` is returned instead. `browser_content(mode="html")`: the `value` attribute of these fields is
+  masked in a copy of the DOM (React copies it from the input), the page itself is untouched. `browser_fill` still
+  reads the real value back from the page (`verified` stays accurate); only the output is masked, including the
+  expected value and the JavaScript fallback. A single definition of sensitive fields, in the localization kit,
+  injected into every page script.
+- Antigravity review (October 18): the rendered text of a sensitive field (textarea, contenteditable) was not
+  masked; a "show password" field without a recognized autocomplete is now identified by its name or id (password,
+  pwd, mot de passe, mdp, cvc...), never a container; non-input components carrying a sensitive autocomplete are
+  masked in the accessibility tree and the HTML.
+- `browser_cdp_send`: `Page.reload` accepted `scriptToEvaluateOnLoad` passed through unchanged (a script injected
+  into the page world on load, like `Page.addScriptToEvaluateOnNewDocument`, which is refused). Now refused before
+  reaching Chrome, with a clear message; a plain reload is still allowed.
+
+### Fixed
+- Incorrect promise: "cookies sealed outside localhost". `browser_eval` and `Runtime.evaluate` (both worlds share the
+  document) can read `document.cookie` (non-HttpOnly cookies), localStorage, sessionStorage, IndexedDB and the result
+  of a `fetch` sent with the user's session, without masking. Kept as is (maximum autonomy; pattern-based masking
+  would be bypassed by the slightest `btoa`) and stated clearly in the tool, the server instructions, the skill and
+  the README: masking applies to the dedicated tools, not to a script nor to raw `browser_cdp_send` responses
+  (`DOM.getOuterHTML`, `Accessibility.getFullAXTree`).
+
+### Changed
+- MCP SDK 2.3.0 (instead of 1.30.0; the 1.x branch only receives security fixes): `MCPServer` (formerly
+  `FastMCP`), advertised version read from `VERSION`.
+- MCP annotations on all 47 tools (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): page
+  reads, local reads, tab management, navigation, and page actions marked destructive (in the user's real sessions, a
+  click, an Enter key press, a checked box or a script can send, delete or confirm). A tool marked "read-only" only
+  sends the bridge commands from its read list (tested), with one deliberate exception: `browser_get_cookies`, which
+  modifies nothing but is still blocked by the emergency stop.
+- Tools are typed exactly (the decorator no longer turned them into `Any`): mistyped test calls fixed.
+
+### Tests
+- Node: content, visual map, search, HTML and accessibility tree contain no sensitive value; typing into a password
+  field, into a card field rewritten by the page, and through the JavaScript fallback returns no value;
+  `Page.reload` with a script refused before reaching Chrome. Mutation checked: without masking, the three masking
+  tests fail.
+- Python: SDK 2, complete annotations consistent with the bridge read list, accurate wording about `browser_eval`
+  (tool, instructions, both copies of the skill, README).
+- Real-world validation (`--full-live`): password and card never read (content, HTML, visual map, search, Chrome
+  accessibility tree), password entry verified and masked, `Page.reload` with a script refused.
+
+### Known issues
+- `Page.captureScreenshot` sometimes hangs for 12 to 20 s in a background tab (both `browser_screenshot` and
+  `browser_vision_inspect`, measured on October 18, unrelated to this version): the real-world validation retries the
+  visual map up to 3 times and counts the hangs. Root cause to be addressed separately.
+
+## [Unpublished] - 2026-10-17 — Antigravity review: regressions fixed
+
+Version 2.7.1. Re-run `install.ps1` (with Antigravity closed), then RELOAD the extension in `chrome://extensions`
+(capabilities `orphan-tabs`, `cdp-page-world`, `local-cookie-values`, `body-masking-allowlist` advertised by ping),
+then open a new conversation in each agent.
+
+### Fixed
+- Orphaned tabs (severe): after an MCP server restart, its tabs stayed attached to the old session and could not be
+  driven, closed, released or adopted. The bridge and the extension now track live sessions: every command and an MCP
+  server heartbeat (every 60 / 1.618 s) record the last sign of life; each MCP server announces its process (header
+  `X-Nexus-Browser-Pid`), which the bridge checks. A session silent for 1.618 x 60 s, or whose process is gone, is
+  dead: its tabs become orphaned. The same agent takes them back (`browser_adopt_tab` without `julien_asked`, and
+  automatically on the first heartbeat if it has no tab), and can close or release them. Never another agent; a live
+  session of the same agent stays protected (ownership is still held per session). `browser_list_tabs`: `state`
+  (`mine`, `orphan`, `other`, `julien`); control panel: "orphelin" badge.
+- `browser_cdp_send`: `Runtime.evaluate` forced into the isolated world prevented reading an application's state.
+  Isolated world by default, page world on request (`world="page"`); the context is always enforced, without the
+  console API; a dialog opened by the evaluation is reported instead of blocking.
+- Cookies: `include_values=True` is back, ONLY for a local development origin (localhost, 127.0.0.1, [::1],
+  *.localhost, *.test) and for cookies of those domains; clear refusal, before any call to Chrome, for any other
+  origin. Never a value by default.
+- Body masking: `token` without an anchor masked `nextPageToken`, `pageToken`, `total_tokens`, `prompt_tokens`,
+  `max_tokens`, `tokenizer`... Allowlist added (pagination, `token_type`, `expires_*`, `tokenizer`), token counters
+  left alone when the value is a number (OpenAI, Anthropic, Gemini), ambiguous keys masked only when the value looks
+  like a secret (known formats: `ya29.`, `ghp_`, `sk-`, JWT... or a long opaque string). Unambiguous secret keys
+  (`access_token`, `refresh_token`, `id_token`, `token`, `password`, `client_secret`...) always masked.
+
+## [Unpublished] - 2026-10-17 — Default CLI identity
+
+### Fixed
+- Default CLI identifier `cli` (3 characters) was refused by the bridge (4 minimum): now `cli-local`. Test added.
+
+## [Unpublished] - 2026-10-17 — Claude review: isolation and secrets in the extension
+
+Version 2.7.0. Re-run `install.ps1` (with Antigravity closed), then RELOAD the extension in `chrome://extensions`
+(the real-world validation and `verify.ps1 -Browser` refuse an outdated extension: version and features advertised by
+ping), then open a new conversation in each agent. Tools that check the installation must read the fingerprint
+through `scripts\empreinte.ps1`.
+
+### Security
+- `browser_cdp_send`: closed list of ALLOWED commands (DOM reads, `Accessibility.getFullAXTree`,
+  `Runtime.evaluate` forced into the isolated world, screenshots, `Input.dispatch*`, display `Emulation.*`,
+  `Network.enable/disable`, Log/Console); everything else refused before reaching Chrome
+  (`Storage.clearDataForOrigin`, `Network.getRequestPostData`, `Network.loadNetworkResource`, `IO.read`,
+  `Fetch.enable`, `Page.addScriptToEvaluateOnNewDocument`, `Page.navigate`...).
+- Tab ownership enforced by the extension: each bridge client identifies itself (agent + session, headers
+  `X-Nexus-Browser-Agent` / `X-Nexus-Browser-Client`, set by the bridge in the signed channel); the tab opened by
+  `browser_new_tab` belongs to that session (`chrome.storage.session`, survives service worker restarts); any page
+  command on another tab (the user's, another agent's, another session's) is refused. Adopting one of the user's tabs
+  only through `browser_adopt_tab(tab_id, julien_asked=True)`, visible in the control panel.
+- `tab_id` required in the schema of every page tool (no more "last tab" on the MCP side).
+- Response bodies: secret fields masked at any depth (JSON, anti-XSSI prefix, forms, truncated JSON, patterns inside
+  a script); no cookie value leaves the bridge anymore (`include_values` removed).
+- Uploads also checked by the bridge (any HTTP client); folders added (`~\.gemini`, `~\.android`,
+  `~\.git-credentials`, `~\.config\gcloud`, `%APPDATA%\gcloud`, Chrome profile, Credentials/Protect...); paths
+  normalized (`\\?\`, `\\.\`, `\\localhost\C$\`, `\\127.0.0.1\C$\`, machine name, junctions and links, trailing
+  dots, case).
+- Isolated world for all extension scripts (main frame included, `chrome.scripting` fallback in ISOLATED): markers,
+  click probes and AX registry invisible to the page and not replaceable by it. Only `browser_eval` and the YouTube
+  transcript (the page's player) run in the page world.
+- Navigation and new tab: http, https, data:, about:blank only (never file://, chrome://, javascript:).
+- Badge and click dot: extension messages only (a page can no longer display fake ones).
+
+### Added
+- Control panel (side panel, neutral style): tabs driven per agent, debugger state, STOP (shared stop file
+  `~\.nexus\stop` set by the bridge, debuggers detached), "Rendre l'onglet" (release tab), bridge state.
+- Tools `browser_adopt_tab`, `browser_release_tab`, `browser_network_record` (debugger kept attached, 600 s at most),
+  `browser_network_stop`.
+- Emergency stop: the bridge cancels in-flight commands (423 response) and notifies the extension, which interrupts
+  key-by-key typing, dragging (button released) and waits, detaches all debuggers and refuses any action.
+- `VERSION`; `scripts\empreinte.ps1` (installed.stamp includes `installer-hote-natif.ps1` and `runtime.ps1`);
+  `scripts\doublon-antigravity.ps1`, `scripts\ancienne-extension.ps1`.
+
+### Changed
+- Debugger: per-tab command counter (replaces the global counter that prevented any detach).
+- Element capture in page coordinates (scrolling added, beyond the viewport); debugging session resumed after a
+  service worker restart (iframe tracking restarted).
+- `windows.create` fallback: id of the created tab, never that of the window.
+- Panel shortcut: Alt+Shift+N (Ctrl+Shift+A is Chrome's "Search tabs").
+- Antigravity: nexus-browser declared by its plugin only (the `mcp_config.json` entry is removed, after a backup);
+  `verify.ps1` reports a duplicate.
+- Skill also copied for Claude Code (`~\.claude\skills`) and Codex (`~\.codex\skills`).
+- `browser_cli.py`: version read from the code, French help, `--tab-id` required, new commands.
+
+### Removed
+- Panel chat (text box, bridge queue, `browser_sidepanel_requests` / `browser_sidepanel_reply`) and its four
+  buttons; dead `popup.html/js`; SoM display from the content script that was never triggered.
+
+### Migration
+- `install.ps1` removes (log `~\.nexus\nexus-browser\install.log`) the old token `~\.nexusagy\bridge-token` and the
+  files of the old native host; `verify.ps1` checks they are gone and reports the old "Antigravity Browser Bridge"
+  extension if a Chrome profile loads it (preferences read, never modified).
+- No caches in the source tree: ruff `cache-dir` and pytest `-p no:cacheprovider` in `pyproject.toml`,
+  `sys.dont_write_bytecode` in the client and bridge modules; `.ruff_cache`, `client\__pycache__` and
+  `native-host\__pycache__` deleted.
+
+## [2.6.0] - 2026-10-16 — Neutral repository, shared by the three agents
+
+Reload the extension (new folder, new identifier) and re-run `install.ps1` on each machine.
+
+### Added
+- Standalone repository, extracted from the former Antigravity package: extension, local bridge, native host,
+  `nexus-browser` MCP server, CLI, Antigravity skill and plugin, tests (Python, Node, real-world validation).
+- `install.ps1`: environment outside the source tree (`~\.nexus\nexus-browser`), native host, "Nexus Browser Bridge"
+  task with no trigger, registration of `nexus-browser` with Claude Code, Codex and Antigravity (plugin and skill
+  included), installation fingerprint.
+- Agent name per registration (`NEXUS_BROWSER_AGENT`: Antigravity, Claude, Codex): default tab group named after it,
+  to see at a glance which agent opened what.
+- Fixed extension identifier (`blcgddmjdkobmgakjffjpgiicjlflgjf`), derived from the public `key` in the manifest: the
+  same on every machine and whatever folder is loaded; the only origin accepted by the bridge and the native host (six
+  identifiers tied to the old folders previously).
+- `verify.ps1`: task, native host, absence of the old task; `-Browser`: bridge reachable and extension loaded and up
+  to date.
+
+### Changed
+- Neutral names: "Nexus Browser Bridge" extension, native host `com.nexus.browser_auth`, protocol `nexus-browser/1`,
+  header `X-Nexus-Browser-Token`, token `~\.nexus\nexus-browser\bridge-token`, exports in
+  `Téléchargements\nexus-browser-exports`, default tab group "Nexus" when no registration is set.
+- MCP server reduced to the browser (Computer Use stays in the former Antigravity package); screenshot cleanup with
+  no dependency on the desktop client.
+- Uploads also refused under `~\.nexus` (bridge token, emergency stop).
+
+### Verified
+- Real-world validation in the user's Chrome: `--mouse` 11/11, `--full-live` 29/29 (`test.ps1 -Full` green four
+  times in a row). First three runs right after loading the extension: 27/29, empty network log for the `/api/data`
+  request (cause not found, not reproduced since); the failure now prints the log and the click response.
+
+### Migration
+- `install.ps1` stops and removes the "NexusAGY Browser Bridge" task (same ports 9224/9225) and the native host
+  `com.nexusagy.bridge_auth`. The old "Antigravity Browser Bridge" extension must be removed from Chrome.
+
+Versions up to 2.4.0 were published as "Antigravity Browser Bridge" in the same public repository; see its git history.

nexus_browser-2.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Piron (https://julienpiron.fr)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexus_browser-2.9.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: nexus-browser
+Version: 2.9.0
+Summary: Your real Chrome, driven by Claude, Codex and Antigravity in background tabs: the nexus-browser MCP server (needs the NexusBrowser bridge and extension)
+Project-URL: Homepage, https://julienpiron.fr/nexusbrowser/
+Project-URL: Repository, https://github.com/pironjulien/NexusBrowser
+Project-URL: Changelog, https://github.com/pironjulien/NexusBrowser/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/pironjulien/NexusBrowser/issues
+Author: Julien Piron
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,antigravity,browser-use,cdp,chrome,claude,codex,computer-use,mcp,mcp-server
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.3.0
+Requires-Dist: websockets<17,>=13.0
+Description-Content-Type: text/markdown
+
+# NexusBrowser
+
+<!-- mcp-name: io.github.pironjulien/nexus-browser -->
+
+[![Release](https://img.shields.io/github/v/release/pironjulien/NexusBrowser)](https://github.com/pironjulien/NexusBrowser/releases)
+[![PyPI](https://img.shields.io/pypi/v/nexus-browser)](https://pypi.org/project/nexus-browser/)
+[![Tests](https://github.com/pironjulien/NexusBrowser/actions/workflows/tests.yml/badge.svg)](https://github.com/pironjulien/NexusBrowser/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Chrome MV3](https://img.shields.io/badge/Chrome-Manifest%20V3-4285F4?logo=googlechrome&logoColor=white)](extension/manifest.json)
+[![Python 3.14](https://img.shields.io/badge/python-3.14-blue?logo=python&logoColor=white)](pyproject.toml)
+[![MCP](https://img.shields.io/badge/MCP-server-7ee2a8)](https://modelcontextprotocol.io)
+
+[![NexusBrowser: your real Chrome, driven by an AI agent in a background tab.](docs/assets/banner.webp)](https://julienpiron.fr/nexusbrowser/)
+
+![NexusBrowser: an AI agent types into a form, picks an option and clicks in a background Chrome tab while the user keeps browsing](docs/assets/demo.webp)
+
+**Your real Chrome, driven by AI agents in background tabs.** NexusBrowser lets Antigravity, Claude and Codex use
+the user's own Chrome (their sessions, their extensions) through one shared local bridge and one MCP server,
+`nexus-browser`. Each agent works in its own background tabs, grouped under its name, with real (trusted) mouse
+and keyboard events sent through the Chrome DevTools Protocol, while the user keeps working in their own tabs.
+
+Version 2.9.0 · Windows 10/11 · Chrome 116+ · Python 3.14 · MIT licence
+
+Part of the Nexus family: [NexusWindows](https://julienpiron.fr/nexuswindows/)
+([Claude](https://github.com/pironjulien/NexusWindows-Claude) ·
+[Codex](https://github.com/pironjulien/NexusWindows-Codex) ·
+[Antigravity](https://github.com/pironjulien/NexusWindows-Antigravity)),
+[NexusBrowser](https://julienpiron.fr/nexusbrowser/) ([repo](https://github.com/pironjulien/NexusBrowser)),
+[NexusAndroid](https://julienpiron.fr/nexusandroid/) ([repo](https://github.com/pironjulien/NexusAndroid)).
+Project page: [julienpiron.fr/nexusbrowser](https://julienpiron.fr/nexusbrowser/).
+
+## Why
+
+Browser automation usually means a separate headless browser (no sessions, no extensions) or screen-level computer
+use that moves the user's cursor and brings the window to the front. NexusBrowser works inside the browser the user
+already uses, without activating the agent's tab or window, and keeps the guard rails in the extension and the
+bridge rather than in the agent: tab ownership, an allowlist of DevTools commands, masked secrets, an emergency stop.
+
+- **Antigravity**: its own browser agent runs in a separate Chrome profile, without the cookies or sign-ins of the
+  user's browsing ([Antigravity docs](https://antigravity.google/docs/ide/separate-chrome-profile/)). NexusBrowser
+  gives it the user's real Chrome.
+- **Claude and Codex** already have their own Chrome extension (Claude in Chrome, the Codex Chrome extension).
+  NexusBrowser complements it where a bridge with the DevTools protocol helps: JavaScript dialogs
+  (`browser_handle_dialog`), detailed network capture with response bodies, elements inside cross-origin iframes,
+  content and Google Docs/Sheets/Slides exports, and downloads.
+
+Until 2.4.0 it was published here as "Antigravity Browser Bridge", for Antigravity only. Since 2.6.0 it is a neutral
+bridge shared by several agents.
+
+## Pieces
+
+| Folder | Role |
+| --- | --- |
+| `extension/` | Chrome MV3 extension "Nexus Browser Bridge": CDP actions, locators, network, dialogs, cross-origin iframes, exports, tab ownership, control panel |
+| `native-host/` | Local bridge (`bridge_server.py`: WebSocket 9224 for the extension, HTTP 9225 for the agents) and native host `com.nexus.browser_auth` |
+| `client/` | MCP server `nexus-browser` (`mcp_server.py`), authenticated transport (`bridge_client.py`), CLI (`browser_cli.py`), shared emergency stop |
+| `skills/`, `plugins/` | Skill (copied for Antigravity, Claude Code and Codex) and Antigravity plugin, by `install.ps1` |
+
+## Tools
+
+47 MCP tools. Tool descriptions and messages are in French; tool and parameter names are in English.
+
+| Area | Tools |
+| --- | --- |
+| Tabs | `browser_list_tabs`, `browser_active_tab` (read only), `browser_new_tab`, `browser_select_tab`, `browser_adopt_tab`, `browser_release_tab`, `browser_group_tabs`, `browser_close_tab`, `browser_reload`, `browser_navigate`, `browser_wait_load` |
+| Input (trusted CDP events) | `browser_click`, `browser_semantic_click`, `browser_hover`, `browser_fill`, `browser_semantic_fill`, `browser_select_option`, `browser_check`, `browser_press_key`, `browser_type_keys`, `browser_drag_and_drop`, `browser_scroll`, `browser_upload`, `browser_handle_dialog` |
+| Finding elements | `browser_find` (Playwright-style locators: role, label, text, placeholder, test id, in every frame), `browser_interactive_map`, `browser_vision_inspect` and `browser_click_mark` (Set-of-Mark badges), `browser_axtree`, `browser_content`, `browser_check_handoff` (2FA, CAPTCHA) |
+| Network and downloads | `browser_network_record`, `browser_network_stop`, `browser_network_requests`, `browser_network_response`, `browser_wait_network_idle`, `browser_download_status`, `browser_wait_download`, `browser_get_cookies` |
+| Output | `browser_screenshot`, `browser_pdf`, `browser_export` (main content as Markdown, text or HTML), `browser_export_gsuite` (Google Docs, Sheets, Slides through Google's export URLs), `browser_export_youtube_transcript`, `browser_logs` |
+| Page access | `browser_eval`, `browser_cdp_send` (allowlisted commands) |
+
+## Install
+
+Requirements: Windows 10 or 11, Chrome, [uv](https://docs.astral.sh/uv/), Python 3.14.
+
+```powershell
+git clone https://github.com/pironjulien/NexusBrowser.git
+cd NexusBrowser
+pwsh -NoProfile -File install.ps1
+```
+
+- Python environment, token, logs, screenshots and exports live in `~\.nexus\nexus-browser` (outside the clone).
+- Scheduled task `Nexus Browser Bridge` with **no trigger**: the bridge starts on demand (first agent call,
+  `schtasks /Run`).
+- Native host `com.nexus.browser_auth` declared to Chrome (HKCU): it computes the extension's proofs, the token never
+  reaches Chrome.
+- MCP server `nexus-browser` registered for Claude Code, Codex and Antigravity when they are installed, each with
+  `NEXUS_BROWSER_AGENT` set to its name (default tab group).
+- When the bridge has to relaunch Chrome, it uses the `Default` profile; extra Chrome flags (language...)
+  can be added with the `NEXUS_CHROME_EXTRA_ARGS` environment variable (allowlist: `--lang`, `--accept-lang`,
+  `--variations-override-country`, `--disable-features=Glic…`, `--force-dark-mode`; anything else is ignored).
+- Migration from the former "Antigravity Browser Bridge": its task (same ports) and native host
+  `com.nexusagy.bridge_auth` are removed.
+
+Then load `extension\` once in `chrome://extensions` (developer mode, "Load unpacked") and remove the old
+"Antigravity Browser Bridge" if present. The extension ID is fixed by the public `key` in `manifest.json`
+(`blcgddmjdkobmgakjffjpgiicjlflgjf`), the same on every PC and whatever the folder; it is the only origin the bridge
+and the native host accept.
+
+### The MCP server from PyPI
+
+Once the bridge and the extension are installed (above), any MCP client can also start the server straight from
+[PyPI](https://pypi.org/project/nexus-browser/), without the clone:
+
+```bash
+claude mcp add nexus-browser --scope user -e NEXUS_BROWSER_AGENT=Claude -- uvx nexus-browser
+```
+
+Without the bridge, the server still starts and lists its 47 tools, and every call answers with a clear error that
+points to the one-time install.
+
+## Security (held by the extension and the bridge, not by the agent)
+
+- **Mutually authenticated bridge** (`nexus-browser/1`): HMAC proofs over both nonces, then every message signed
+  with a per-connection key and a strict sequence number. HTTP requires `X-Nexus-Browser-Token` and refuses any
+  browser origin.
+- **Tab ownership**: every bridge client identifies itself (agent + session headers, forwarded by the bridge in the
+  signed channel). A tab opened by `browser_new_tab` belongs to that session (`chrome.storage.session`); any page
+  command on another tab (the user's, another agent's) is refused. A tab of the user only through
+  `browser_adopt_tab(tab_id, julien_asked=True)` (the parameter keeps its historical name). `tab_id` is mandatory on
+  every page tool. A session whose MCP process is gone (or silent for 1.618 x 60 s; servers beat every 37 s) leaves
+  **orphan** tabs: the same agent can reclaim (`browser_adopt_tab`, also automatically at startup), close or release
+  them; never another agent.
+- **CDP allowlist** for `browser_cdp_send`; every extension script runs in an **isolated world** (only
+  `browser_eval`, the YouTube transcript and `browser_cdp_send(..., world="page")` touch the page's world).
+- **Secrets**: secret headers, URL parameters and JSON/form body fields masked (pagination tokens and LLM token
+  counters kept); cookie values only for local development origins (`include_values=True`); uploads refused by the
+  bridge itself from secret folders (normalized paths). The value of a password, one-time code or payment card field
+  (`type=password`, `autocomplete` current-password, new-password, one-time-code, cc-number, cc-csc, cc-exp) never
+  leaves the page: `browser_content` (html mode included), `browser_vision_inspect`, `browser_find`,
+  `browser_axtree` and the value read back by `browser_fill` return `[valeur masquée]` instead.
+- **`browser_eval` is full access to the page, nothing masked**: like `browser_cdp_send(Runtime.evaluate)` (both
+  worlds share the document), it reads what the page reads (non-HttpOnly cookies through `document.cookie`,
+  localStorage, sessionStorage, IndexedDB, form fields) and its `fetch` carries the user's session. The masking
+  above covers the dedicated tools, not scripts nor the raw Chrome replies of `browser_cdp_send`
+  (`DOM.getOuterHTML`, `Accessibility.getFullAXTree`...): kept on purpose, said plainly in the tool, the skill and
+  the server instructions. `Page.reload` with `scriptToEvaluateOnLoad` is refused (script injected at load).
+- **Emergency stop** (Ctrl+Alt+Shift+Esc, STOP button of the control panel, `~\.nexus\stop`): commands already
+  running are cancelled (typing, drag, waits), debuggers detached, every action refused for 120 s. The same file
+  protocol is shared with the [NexusWindows](https://julienpiron.fr/nexuswindows/) agents.
+- **Control panel** (side panel, Alt+Shift+N): tabs driven by each agent, debugger state, STOP, give a tab back.
+- Whoever holds the bridge token controls the browser session: keep `~\.nexus\nexus-browser\bridge-token` private.
+
+## Checks
+
+```powershell
+pwsh -NoProfile -File test.ps1         # offline: ruff, Pyright, pytest (real bridge on ephemeral ports), Node tests
+pwsh -NoProfile -File test.ps1 -Full   # plus real validation in the user's Chrome: --mouse then --full-live
+pwsh -NoProfile -File verify.ps1 -Browser  # task, native host, bridge reached, loaded extension up to date
+```
+
+`test.ps1` uses the environment created by `install.ps1`.
+
+## Privacy
+
+NexusBrowser runs entirely on your PC: a Chrome extension, a local bridge bound to `127.0.0.1` (authenticated by a
+local token) and an MCP server. It has no account, no telemetry, no analytics and no remote server; nothing is sent
+to the author or to any third party.
+
+- **What it reads**: in the tabs the agent opened (or a tab of yours you explicitly let it adopt): page text and
+  accessibility tree, screenshots, console logs, network requests (headers and secret fields masked), cookies when
+  `browser_get_cookies` is called. Password, code and card values are masked in reads and drawn as dots in
+  screenshots and PDFs (every frame, cross-origin ones included); console logs are masked like network bodies;
+  `browser_eval` and `Runtime.evaluate` through `browser_cdp_send` do have full access to the page.
+- **Network**: pages are loaded by your own Chrome with your own sessions, as if you browsed them. Exports (Google
+  Docs, Sheets, Slides, YouTube transcripts) are fetched from those sites in your session.
+- **Where it goes**: tool results are returned to the AI client you connected (Antigravity, Claude, Codex…), which
+  may send them to its model provider under its own privacy policy.
+- **What it stores**, under `~/.nexus/nexus-browser/`: the Python environment, the bridge token, `bridge.log`
+  (connection and emergency-stop events, rotated at 1 MB, three backups), `install.log`, screenshots (at most 50,
+  each kept under 24 hours) and the exports you ask for. The extension keeps tab ownership in Chrome's session
+  storage, cleared when Chrome closes.
+- **Removing it**: remove the extension from Chrome, delete the scheduled task `Nexus Browser Bridge` and the
+  registry key `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.nexus.browser_auth`, then delete
+  `~/.nexus/nexus-browser/`.
+
+Questions or concerns: open an issue on this repository.
+
+## Limits
+
+- Windows and Chrome only (Manifest V3, `chrome.debugger`). While the debugger is attached, Chrome shows its "is
+  being debugged" banner on the agent tab. Protected pages (`chrome://`, the Web Store) cannot be scripted.
+- Tab ownership is per MCP process: sub-agents of one conversation share it.
+- The YouTube transcript reads the page's own player (page world).
+- Tool descriptions, messages and code comments are in French.
+
+## Licence
+
+MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Julien Piron.