browser-attach 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.2] - 2026-10-29
+
+### Fixed
+- Extension description fits the Chrome Web Store limit of 132 characters (the upload was rejected at 158).
+
+## [0.1.1] - 2026-10-29
+
+### Changed
+- Every agent session gets its own browser window; sessions never share an active tab and the user's windows are never touched (protocol 20: reload the extension).
+- The extension has icons and a user-facing description, and connects only to a daemon on this machine (127.0.0.1, localhost, [::1]).
+- `PORT_IN_USE` explains the usual cause (browser-attach running on the other side of WSL/Windows).
+
+### Fixed
+- Windows: packaging (esbuild via its JS API), naming the process that holds the port.
+- Node 20: unit test discovery.
+
+## [0.1.0] - 2026-10-09
+
+First public release.
+
+### Added
+- Chrome MV3 extension that drives the user's real, logged-in Chrome with no debug port (content scripts, WebSocket on `127.0.0.1`).
+- `browser-attach` CLI and background daemon: per-session tabs, page views with element refs, click/type/select/upload, find, screenshots (viewport, element, full page, annotated), JavaScript evaluation, network log.
+- MCP server with the same tools (`bundle/bridge.mjs`).
+- `browser-attach setup`: installs the agent skill, copies the extension to a stable per-user folder, adds the Claude Code permission rules to `~/.claude/settings.json`. `browser-attach extension path` prints the folder to load; `browser-attach status` reports when the extension is not connected.
+- npm package `browser-attach` bundling the CLI, the daemon and the built extension (same version for all three); GitHub Releases with the extension as a zip.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShunL12324 and contributors
+
+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.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# browser-attach
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let an AI agent (or you, from the shell) drive your **real, logged-in Chrome**.
+
+`browser-attach` is a Chrome extension plus a small local daemon and CLI. The agent opens pages, reads them as compact text with stable element refs, clicks, types and takes screenshots, in the browser profile you already use: your cookies, your logins, your extensions.
+
+## How it differs from CDP-based tools
+
+| | browser-attach | Playwright / Puppeteer / chrome-devtools MCP |
+| --- | --- | --- |
+| Browser | the Chrome you already run | a fresh or specially launched browser |
+| Logged-in sessions | yes, as they are | log in again, or copy a profile |
+| Debug port (`--remote-debugging-port`) | none | required (an open, unauthenticated control port) |
+| "Chrome is being controlled by automated software" banner | no | yes |
+| Control path | extension content scripts, a WebSocket on `127.0.0.1` | Chrome DevTools Protocol |
+
+The extension does the DOM work, the daemon relays commands from any number of agent sessions. Each session sees only its own tabs.
+
+## Install
+
+Requires Node.js 20+ and Chrome 124+ (Chromium-based browsers work too).
+
+The package is distributed through GitHub Releases (a private repository works; log in once with `gh auth login`):
+
+```sh
+gh release download -R ShunL12324/browser-attach -p '*.tgz'
+npm i -g ./browser-attach-*.tgz
+browser-attach setup
+```
+
+`setup` is safe to run again. It installs the agent skill, copies the extension to a stable folder, and allows the CLI in Claude Code's `~/.claude/settings.json` (it asks first; `--yes` skips the question, `--no-permissions` skips the step). Then load the extension once. The extension is not on the Chrome Web Store (yet), so it is installed in developer mode:
+
+1. Open `chrome://extensions` and turn on **Developer mode** (top right).
+2. Click **Load unpacked** and pick the folder `setup` printed. `browser-attach extension path` prints it again (`~/.local/share/browser-attach/extension`, or `%LOCALAPPDATA%\browser-attach\extension` on Windows).
+3. Check the connection:
+
+```sh
+browser-attach status
+```
+
+Optional: on the extension card, **Details → Allow User Scripts** lets `eval` run on pages with a strict CSP.
+
+**Upgrading:** download the newest release tarball, `npm i -g` it, run `browser-attach setup`, then press **Reload** on the extension card. The CLI and the extension of one release always match; a running daemon of an older build restarts by itself.
+
+## Quick start
+
+```sh
+$ browser-attach open https://example.com
+open tab 412 ok · 1 refs
+"Example Domain" https://example.com/ · 1 refs
+- h1: "Example Domain"
+- link: "Learn more" [e1]
+$ browser-attach click e1
+```
+
+Big pages print an outline and a file path; every control line in the file carries its ref (`- button: "Submit" [e12]`), so agents read it with their normal Read/Grep tools.
+
+## CLI reference
+
+`browser-attach help` lists everything, `browser-attach <command> --help` has details.
+
+| Command | What it does |
+| --- | --- |
+| `open URL` / `goto URL` / `back` / `reload` | open a new tab / navigate the current one; print the page |
+| `view [--ref eN]` | read the page (inline when small, else outline + file) |
+| `find TEXT` / `find --regex RE` | matching lines with refs and context |
+| `shot [--ref eN] [--full] [--annotate]` | screenshot (viewport, element, full page, or controls boxed with their refs) |
+| `click REF`, `type REF TEXT [--submit]`, `press KEY`, `select REF VALUE`, `hover REF`, `upload REF FILE` | act on elements |
+| `scroll`, `wait`, `inspect`, `eval`, `net` | scroll, wait for a condition, read element fields, run JavaScript, recent network calls |
+| `tabs [new\|switch\|close]` | the tabs of this session |
+| `status`, `sessions`, `close [--all]`, `daemon start\|stop\|restart\|logs`, `config` | admin |
+| `setup`, `extension path`, `skill install` | installation |
+
+Global flags: `-s NAME` session, `-t TAB`, `--json`, `--quiet`, `--port N`. Exit codes: 0 ok, 1 tool error, 2 usage, 3 browser/daemon unavailable, 5 timeout. Files go to `~/.cache/browser-attach/out/<session>/`.
+
+## Use with AI agents
+
+**Claude Code.** `setup` installs the `browser-attach` skill (`~/.claude/skills/browser-attach/SKILL.md`) and allows these rules in `~/.claude/settings.json`: `Skill(browser-attach)`, `Bash(browser-attach:*)`, `Read(~/.cache/browser-attach/**)` (plus `PowerShell(browser-attach *)` on Windows). Then just ask: *"open example.com and tell me what's on it"*. Every Claude Code session gets its own tabs automatically.
+
+**Codex and other agents.** The skill is also written to `~/.agents/skills/browser-attach/`. An agent without skills support only needs to be told to run `browser-attach help`.
+
+**MCP clients.** The package also contains an MCP server (stdio) with the same tools: `node "$(npm root -g)/browser-attach/bundle/bridge.mjs"` as the server command.
+
+## Security notes
+
+- The daemon and the extension talk over a WebSocket bound to `127.0.0.1` only (port 17329), the CLI and the daemon over a user-private local socket (a named pipe on Windows). Nothing listens on the network, and no Chrome debug port is opened.
+- Anyone who can run commands as your user can drive your browser, exactly as with any local automation. The agent acts with your logins: use `-s` sessions and review what you allow.
+- Extension permissions and why: `tabs` (open, list, switch, close the agent's tabs), `scripting` and host access to all sites (read and act on the pages you point the agent at), `webNavigation` (reach every frame of a page), `cookies` (the `get_cookie` tool), `storage` (connection settings, which tabs belong to agent sessions), `alarms` (keep the service worker connected), `userScripts` (optional `eval` fallback on strict-CSP pages). There is no `debugger` permission.
+- Values of password, one-time-code and card-number fields are shown as `[redacted]` in page views and results. Browser-internal pages (`chrome:`, the Web Store, other extensions) are never scripted.
+- No telemetry. The extension and the CLI never contact a remote server.
+
+## Troubleshooting
+
+- `browser-attach status` says the extension is not connected: load or reload it (steps above), check that Chrome is running. The extension reconnects within seconds.
+- `PORT_IN_USE`: another program holds port 17329, which the extension connects to by default. Stop that program.
+- Daemon log: `browser-attach daemon logs`.
+
+## Development and releases
+
+See [docs/development.md](docs/development.md). Releases are tags `vX.Y.Z`: the workflow attaches the package tarball and `browser-attach-extension-vX.Y.Z.zip` to the GitHub Release. It needs no secrets (`GITHUB_TOKEN` is provided by Actions).
+
+## License
+
+[MIT](LICENSE)