nekoro-browser 0.1.0__tar.gz

nekoro_browser-0.1.0/.claude/skills/nekoro-browser/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: nekoro-browser
+description: 浏览器自动化——打开网页、搜索、点击、截图、执行 JS、填表、上传文件、处理对话框。通过 Chrome 扩展的 chrome.debugger API 操控用户日常浏览器，保留登录态，不开调试端口。触发词："浏览器"、"打开网页"、"搜索"、"截图"、"点击"、"填表"、"上传文件"、"自动化操作"。
+allowed-tools: Bash(nekoro-browser:*) Bash(python:*) Read Edit Write
+---
+
+# nekoro-browser
+
+通过 Chrome 扩展 + 持久 WebSocket 操控用户日常 Chrome 的 CLI 工具。不需要
+`--remote-debugging-port`（Chrome 136 起该方式无法接默认 profile），保留真实登录态。
+
+**完整命令参考、故障排查、领域技能见仓库根目录 [`SKILL.md`](../../../SKILL.md)——先读那份，本文件只补 Claude Code 场景的要点。**
+
+## 前置条件
+
+```bash
+pip install -e .    # 或 uv pip install -e .，注册 nekoro-browser 命令
+```
+
+加载 Chrome 扩展：`chrome://extensions` → 开发者模式 → 加载已解压的扩展程序 → 选
+`extension/` 目录（`nekoro-browser --extension-path` 打印绝对路径）。未打包扩展会被
+Chrome 更新/重启后自动停用，`--doctor` 说 SW 不响应时先去那页确认它还开着。
+
+## 快速开始
+
+```bash
+# 终端 1：启动 daemon（前台，保持打开）
+nekoro-browser
+
+# 终端 2：验证
+nekoro-browser --doctor
+echo "page_info()" | nekoro-browser
+```
+
+daemon 默认监听 `127.0.0.1:28417`（选此端口是为了不与同类工具 `@jackwener/opencli` 的
+19825 撞车，若你机器上也装了 OpenCLI，两者可共存但同一时刻按需只启一个 daemon）。
+
+改端口：Python 侧 `nekoro-browser --port 30500` 或环境变量 `NEKORO_PORT`，
+扩展侧在扩展详情页的「扩展程序选项」里设成同一个。客户端不用重复传参——
+daemon 把实际端口写进 `<数据目录>/port`，管道模式自己会读。
+
+## 每次调用前
+
+检查 daemon 是否存活（`nekoro-browser --doctor`），死了 `nekoro-browser --reload-ext`
+或重启；扩展 service worker 偶尔需要在 `chrome://extensions` 手动重载（尤其 Chrome
+刚重开时）。
+
+## 自愈
+
+缺少函数时编辑 `src/nekoro_browser/agent_helpers.py` 添加——**只有这个文件**每次
+`/exec` 前会自动 reload，改完立即生效、无需重启 daemon。改 `helpers.py` 本身需要重启
+daemon 才生效（daemon 启动时导入一次）。

nekoro_browser-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+# 库不锁依赖版本（本来就零依赖），锁文件只是本地噪音
+# 注意：gitignore 不支持行尾注释，注释必须独占一行，否则整行都会被当成 pattern
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# 本地一次性脚本（作者自用，不进仓库；目录本身也不跟踪）
+scripts/

nekoro_browser-0.1.0/AGENTS.md

@@ -0,0 +1,46 @@
+nekoro-browser is a CLI that lets an agent drive the user's daily Chrome via a MV3
+extension (`chrome.debugger` API) + a local daemon, keeping the real login state —
+no `--remote-debugging-port` (Chrome 136+ blocks that on the default profile anyway).
+
+# Code priorities
+- Clarity
+- Precision
+- Low verbosity
+- Never fabricate success — helpers return `{"ok": false, "error": ...}` on failure,
+  not a silently-wrong `{"ok": true}`
+
+# Overview
+Two halves, one wire (HTTP + WebSocket, same port):
+- `extension/` — MV3 extension. `background.js` is the service worker: WS transport to
+  the daemon, `chrome.debugger` attach/CDP dispatch, dialog auto-handling, tab lifecycle.
+  `keepalive.js` is a content script that gives the service worker an independent wake
+  vector (MV3 workers get evicted; a plain WS/alarm keep-alive alone isn't reliable).
+- `src/nekoro_browser/` — the daemon + CLI.
+  - `daemon.py` — long-lived middleman process between the extension and the agent's `-c` code
+  - `bridge.py` — the WS/HTTP transport
+  - `lifecycle.py` — pid file, process fingerprint, stale-daemon self-heal
+  - `helpers.py` — CDP wrapper functions auto-imported into `-c` scripts, each a thin
+    (≤10 line) wrapper over one CDP capability
+  - `cli.py` — the `nekoro-browser` command
+  - `mcp_server.py` — the `nekoro-browser-mcp` command: stdio JSON-RPC MCP server for
+    clients that don't read skill files (Cursor / Cline / Claude Desktop). Tools are
+    reflected off `helpers.py` via `inspect.signature`, then forwarded to the same
+    daemon `/exec` endpoint the CLI uses — no second execution path to keep in sync.
+
+`SKILL.md` tells agents how to use the CLI and lists every helper. `README.md` covers
+install + quick start for humans.
+
+An agent operating nekoro-browser edits two places:
+- `src/nekoro_browser/agent_helpers.py` — task-specific browser helpers the agent adds
+  at runtime; hot-reloaded via `reload_agent_helpers()`, no daemon restart needed
+- `domain-skills/` — Markdown notes on specific sites, written and read by the agent.
+  Empty by default and never imported; workflows go in `agent_helpers.py`.
+
+# Testing
+`tests/*.py` are stdlib-style, not pytest: `assert` + a final `print("ALL OK")`, run via
+`uv run python tests/test_X.py`. Extension JS has no unit-test surface — verify syntax
+with `node --check`, behavior needs a live Chrome.
+
+# Contributing
+Consider what is really needed. Prefer the smallest diff that fixes the bug. Don't add
+speculative config/flags for scenarios that aren't happening yet.

nekoro_browser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nekoro
+
+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.

nekoro_browser-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: nekoro-browser
+Version: 0.1.0
+Summary: Lightweight browser automation CLI + MCP server driving your everyday Chrome via the extension chrome.debugger API — keeps your login state, no --remote-debugging-port
+Project-URL: Homepage, https://github.com/zeshuochen/nekoro-browser
+Project-URL: Repository, https://github.com/zeshuochen/nekoro-browser
+Project-URL: Issues, https://github.com/zeshuochen/nekoro-browser/issues
+Project-URL: Documentation, https://github.com/zeshuochen/nekoro-browser/blob/master/SKILL.md
+License: MIT
+License-File: LICENSE
+Keywords: agent,browser-automation,cdp,chrome,chrome-devtools-protocol,llm,mcp,model-context-protocol,playwright-alternative
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="extension/icons/icon-128.png" width="80" alt="nekoro-browser">
+</p>
+
+<h1 align="center">nekoro-browser</h1>
+
+<p align="center">
+  <a href="https://github.com/zeshuochen/nekoro-browser/actions/workflows/tests.yml"><img src="https://github.com/zeshuochen/nekoro-browser/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
+  <a href="#mcp-cursor--cline--claude-desktop"><img src="https://img.shields.io/badge/MCP-supported-8A2BE2" alt="MCP supported"></a>
+</p>
+
+<p align="center">
+Lightweight browser automation CLI + MCP server. Drives your everyday Chrome through an extension — <b>keeps your login state</b>, <b>no debug port</b>, <b>no banners</b>.<br>
+<sub><a href="README.zh-CN.md">中文</a></sub>
+</p>
+
+---
+
+## Why Not `--remote-debugging-port`?
+
+Since Chrome 136, `--remote-debugging-port` / `--remote-debugging-pipe` **refuse the default profile** — you must point Chrome at a non-default `--user-data-dir`, i.e. a clean instance with none of your logins. An extension's `chrome.debugger` is not subject to that restriction, which is why nekoro goes through an extension.
+
+| | CDP WebSocket | playwright-cli | opencli | **nekoro-browser** |
+|------|:--:|:--:|:--:|:--:|
+| Approach | `--remote-debugging-port` | Playwright extension | OpenCLI extension | Custom extension + persistent WebSocket |
+| Install | one flag | `npm i -g` (~200MB) | npm / desktop app | `pip install` (stdlib only, zero deps) |
+| Login state | ❌ fresh instance | ✅ | ✅ | ✅ |
+| Modify the extension | — | Edit Playwright source | Edit OpenCLI source | ✅ right in this repo |
+| Self-healing | ❌ | ❌ | ❌ | ✅ Agent edits helpers at runtime |
+| MCP | ❌ | ✅ (separate `@playwright/mcp`) | ❌ | ✅ built in, 45 tools via `nekoro-browser-mcp` |
+
+## Quick Start
+
+**1 — Install** (Python 3.12+, zero third-party dependencies)
+
+```bash
+git clone https://github.com/zeshuochen/nekoro-browser
+cd nekoro-browser
+pip install -e .
+```
+
+**2 — Load the extension**
+
+```bash
+nekoro-browser setup
+```
+
+`setup` copies the extension directory to your clipboard and then waits — up to three
+minutes — until the extension actually connects, so you find out it worked instead of
+guessing. Meanwhile you do the part Chrome reserves for humans: open `chrome://extensions/`,
+turn on **Developer mode**, click **Load unpacked**, paste the directory.
+
+**3 — Start the daemon** — give it its own terminal and **leave it open**; it runs in the
+foreground and closing that window stops it
+
+```bash
+nekoro-browser
+```
+
+**4 — Drive the browser** from anywhere else
+
+```bash
+echo "page_info()" | nekoro-browser
+# → {"ok": true, "result": {"title": "...", "url": "..."}}
+```
+
+That's it. If step 4 says the daemon isn't running, or a command times out, run
+`nekoro-browser --doctor` — it checks the daemon, the extension and the service worker
+separately and tells you which one is down.
+
+## Examples
+
+Send a multi-step flow in one shot with a heredoc. Every helper is a top-level `await`:
+
+```bash
+nekoro-browser <<'PY'
+await new_tab("https://example.com")
+print((await page_info())["title"])            # Example Domain
+print((await get_markdown(max_chars=200))["result"])
+print((await state(max_items=3))["result"])    # indexed interactive elements, model-ready
+await close_tab()
+PY
+```
+
+`state()` numbers the elements and `click_index(n)` clicks by number — the model never has to guess a CSS selector:
+
+```bash
+nekoro-browser <<'PY'
+await navigate("https://github.com/search?q=browser+automation&type=repositories")
+await wait_for_load()
+print((await state(max_items=40))["result"])
+await click_index(12)
+PY
+```
+
+All helpers are documented in [SKILL.md](SKILL.md).
+
+## MCP (Cursor / Cline / Claude Desktop)
+
+Every function in `helpers.py` is reflected into an MCP tool (45 today) — no glue code:
+
+```json
+{
+  "mcpServers": {
+    "nekoro-browser": {
+      "command": "nekoro-browser-mcp"
+    }
+  }
+}
+```
+
+The daemon still has to be running in another terminal (`nekoro-browser`) — the MCP server just forwards tool calls to it over the same authenticated path as `echo ... | nekoro-browser`. Two escape hatches ship as tools: `cdp` (raw CDP command) and `exec_python` (arbitrary Python in the daemon namespace — a whole multi-step flow in one round trip).
+
+Screenshots come back as image content so clients can render them. A helper's own failure (`{"ok": false}`) is surfaced as `isError` rather than being dressed up as success.
+
+## API
+
+| Category | Commands |
+|----------|----------|
+| Navigation | `navigate(url)`, `new_tab(url)`, `list_tabs()`, `switch_tab(id)`, `close_tab(id)` |
+| Page info | `page_info()`, `page_html()`, `page_text()`, `get_markdown()`, `state()` |
+| JavaScript | `js(code)`, `cdp(method, **p)`, `cdp_batch(*cmds)` |
+| Interaction | `click_selector(sel)`, `click_index(n)`, `click_at_xy(x,y)`, `type_text(t)`, `fill_input(sel,t)`, `press_key(k)`, `upload_file(sel,path)` |
+| Dialogs | `dialog_off()`, `get_last_dialog()` |
+| Waiting | `wait_for_load()`, `wait_selector(sel)`, `wait_for_network_idle()`, `sleep(s)` |
+| Screenshots | `capture_screenshot()`, `capture_screenshot("jpeg", 90)` |
+
+## Architecture
+
+```
+Chrome extension (background.js) —— chrome.debugger / CDP
+        ↕ persistent WebSocket
+Python daemon (127.0.0.1:28417)
+        ↕ HTTP /exec (token auth)
+CLI (nekoro-browser)  ·  MCP server (nekoro-browser-mcp)
+```
+
+`helpers.py` (46 thin wrappers) → CDP commands, each ≤10 lines, none of them aware of any particular website.
+
+`lifecycle.py` manages the daemon: pid file + process fingerprint (avoids killing a reused pid), self-heal on stale daemon (CDP probe fails → auto cleanup and restart), localhost requests bypass the system proxy.
+
+The extension is hardened against MV3 service worker eviction: a `content_scripts` heartbeat (an independent wake vector living in the page, reconnects and wakes the SW even after it's killed) + `onStartup` (reconnects instantly on Chrome cold start) + reattaches the last-driven tab after a restart instead of drifting to a blank tab.
+
+## CLI
+
+| Command | What it does |
+|---------|---------------|
+| `nekoro-browser` | Start the daemon (foreground) |
+| `nekoro-browser setup` | Guided install: extension path + opens chrome://extensions + waits for it to connect |
+| `nekoro-browser --doctor` | End-to-end diagnostic (daemon + extension + SW all alive?) |
+| `nekoro-browser --stop` | Stop the daemon |
+| `nekoro-browser --restart` | Stop and restart (foreground) |
+| `nekoro-browser --reload-ext` | Reload the extension's service worker — run before a batch job for a clean state |
+| `nekoro-browser --extension-path` | Print the extension directory (for "Load unpacked") |
+| `nekoro-browser --port N` | Run the daemon on port N (default 28417) |
+| `nekoro-browser -c "code"` | Run one snippet, print the result |
+| `nekoro-browser --timeout N` | Seconds to allow a snippet (default 120 — page loads are slow) |
+| `echo "code" \| nekoro-browser` | Pipe mode (daemon must already be running) |
+
+## Configuration
+
+The daemon listens on **28417** by default. To change it:
+
+| Side | How |
+|------|-----|
+| Python (daemon + CLI + MCP) | `nekoro-browser --port 30500`, or set `NEKORO_PORT=30500` |
+| Extension | Extension details → **Extension options** → set the port → Save (reconnects immediately, no reload) |
+
+Both sides must agree. Clients don't need the flag repeated: the daemon records its
+actual port in `<data dir>/port`, so a plain `echo ... | nekoro-browser` finds a daemon
+running on a non-default port. Precedence is `--port` > `NEKORO_PORT` > that file > default.
+
+## Self-Healing
+
+`src/nekoro_browser/agent_helpers.py` is editable at runtime and reloaded on every `/exec`. When an agent hits a gap, it appends the missing function there — effective on the next call, no daemon restart, no extension reload.
+
+`domain-skills/` is where site knowledge goes (page structure, selectors, gotchas) — Markdown only, and empty by default since everyone automates different sites. Write a workflow against your notes, drop it into `agent_helpers.py`, same convention (`daemon` as first argument). See [`domain-skills/README.md`](domain-skills/README.md).
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Windows | Primary development platform, exercised end to end |
+| Linux / macOS | The code has the branches (XDG dirs, `chmod 600` token, `/proc` and `ps` liveness probes) and CI runs the unit tests on all three, **but the full "Chrome + extension" loop has never been run on a real macOS/Linux box** — reports welcome |
+
+## Known Limitations
+
+- **Unpacked extensions get disabled by Chrome.** An extension installed via "Load unpacked" may be switched off automatically after a Chrome update or restart, or hidden behind the "Disable developer mode extensions" prompt. When `--doctor` reports Extension/SW not responding, re-enable it in `chrome://extensions/` first. This project is **not published to the Chrome Web Store**, so the limitation is not going away soon.
+- **Service worker keepalive is not 100%.** MV3 eviction timing is Chrome's call. The heartbeat + `onStartup` + reattach cover the vast majority of cases, but unattended long-running cron jobs should still health-check with `--doctor` and retry.
+- **One active tab at a time.** Tabs can be listed and switched (`list_tabs` / `switch_tab`), but commands always go to the current active tab — there are no parallel sessions.
+- **The MCP server handles requests serially.** During a `wait_selector(timeout=90)` every other request on that connection (including `ping`) queues behind it. Open separate client connections if you need concurrency.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Daemon not running` | Daemon not started | Run `nekoro-browser` in terminal 1 |
+| CDP timeout | Extension not connected / service worker asleep | `nekoro-browser --doctor` to diagnose; try `--reload-ext` or manually reload in `chrome://extensions` |
+| Extension disabled by Chrome | Unpacked extension + Chrome update | Re-enable it in `chrome://extensions/`, then re-run `--doctor` |
+| Page unchanged | Extension not attached to tab | Open a regular (non-chrome://) page, restart daemon |
+| Port in use | Stale process | Kill the process on port 28417, or just run `nekoro-browser --stop` |
+
+## Security
+
+The daemon listens on `127.0.0.1` and `/exec` runs arbitrary Python, so the transport is guarded:
+
+- **CLI / MCP → daemon** (`/exec`, `/raw`): a per-session token is written to a user-private file (`%LOCALAPPDATA%\nekoro-browser\token`, `chmod 600` on POSIX). Clients read it and send `X-Nekoro-Token`; missing/wrong token → `403`. Web pages and remote hosts can't read local files, so they can't obtain it. `/ping` stays open.
+- **Extension → daemon** (`/ws`): the handshake `Origin` must be `chrome-extension://…`; a web page's `WebSocket` to localhost carries its own origin and is rejected.
+
+Same-user local processes can read the token file — that boundary matches the OS user account, as with browser-harness's `chmod 600`.
+
+## Feedback
+
+Hit a problem, or missing a helper you need? Open an
+[issue](https://github.com/zeshuochen/nekoro-browser/issues).
+For bugs, include the output of `nekoro-browser --doctor`, your Chrome version and OS — saves a round trip.
+
+PRs welcome. Run the tests first: `for f in tests/test_*.py; do python "$f"; done` (CI runs them on all three platforms too).
+
+---
+
+## Acknowledgments
+
+Core architecture derived from:
+
+- **[browser-harness](https://github.com/browser-use/browser-harness)** — thin-wrapper philosophy (each function is a CDP alias, ≤10 lines), pipe mode, self-healing `agent_helpers.py`, domain-skills directory structure, `cdp()` raw access
+- **[browser-act](https://github.com/browser-act/skills)** — `state()` indexed element tree, `*[N]` change markers, `waitSelector()` state polling, `getMarkdown()` page extraction
+- **[Playwright](https://github.com/microsoft/playwright)** — CDP `Input.dispatchMouseEvent` real mouse events (`isTrusted:true`), extension + daemon dual-path architecture

nekoro_browser-0.1.0/README.md

@@ -0,0 +1,230 @@
+<p align="center">
+  <img src="extension/icons/icon-128.png" width="80" alt="nekoro-browser">
+</p>
+
+<h1 align="center">nekoro-browser</h1>
+
+<p align="center">
+  <a href="https://github.com/zeshuochen/nekoro-browser/actions/workflows/tests.yml"><img src="https://github.com/zeshuochen/nekoro-browser/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
+  <a href="#mcp-cursor--cline--claude-desktop"><img src="https://img.shields.io/badge/MCP-supported-8A2BE2" alt="MCP supported"></a>
+</p>
+
+<p align="center">
+Lightweight browser automation CLI + MCP server. Drives your everyday Chrome through an extension — <b>keeps your login state</b>, <b>no debug port</b>, <b>no banners</b>.<br>
+<sub><a href="README.zh-CN.md">中文</a></sub>
+</p>
+
+---
+
+## Why Not `--remote-debugging-port`?
+
+Since Chrome 136, `--remote-debugging-port` / `--remote-debugging-pipe` **refuse the default profile** — you must point Chrome at a non-default `--user-data-dir`, i.e. a clean instance with none of your logins. An extension's `chrome.debugger` is not subject to that restriction, which is why nekoro goes through an extension.
+
+| | CDP WebSocket | playwright-cli | opencli | **nekoro-browser** |
+|------|:--:|:--:|:--:|:--:|
+| Approach | `--remote-debugging-port` | Playwright extension | OpenCLI extension | Custom extension + persistent WebSocket |
+| Install | one flag | `npm i -g` (~200MB) | npm / desktop app | `pip install` (stdlib only, zero deps) |
+| Login state | ❌ fresh instance | ✅ | ✅ | ✅ |
+| Modify the extension | — | Edit Playwright source | Edit OpenCLI source | ✅ right in this repo |
+| Self-healing | ❌ | ❌ | ❌ | ✅ Agent edits helpers at runtime |
+| MCP | ❌ | ✅ (separate `@playwright/mcp`) | ❌ | ✅ built in, 45 tools via `nekoro-browser-mcp` |
+
+## Quick Start
+
+**1 — Install** (Python 3.12+, zero third-party dependencies)
+
+```bash
+git clone https://github.com/zeshuochen/nekoro-browser
+cd nekoro-browser
+pip install -e .
+```
+
+**2 — Load the extension**
+
+```bash
+nekoro-browser setup
+```
+
+`setup` copies the extension directory to your clipboard and then waits — up to three
+minutes — until the extension actually connects, so you find out it worked instead of
+guessing. Meanwhile you do the part Chrome reserves for humans: open `chrome://extensions/`,
+turn on **Developer mode**, click **Load unpacked**, paste the directory.
+
+**3 — Start the daemon** — give it its own terminal and **leave it open**; it runs in the
+foreground and closing that window stops it
+
+```bash
+nekoro-browser
+```
+
+**4 — Drive the browser** from anywhere else
+
+```bash
+echo "page_info()" | nekoro-browser
+# → {"ok": true, "result": {"title": "...", "url": "..."}}
+```
+
+That's it. If step 4 says the daemon isn't running, or a command times out, run
+`nekoro-browser --doctor` — it checks the daemon, the extension and the service worker
+separately and tells you which one is down.
+
+## Examples
+
+Send a multi-step flow in one shot with a heredoc. Every helper is a top-level `await`:
+
+```bash
+nekoro-browser <<'PY'
+await new_tab("https://example.com")
+print((await page_info())["title"])            # Example Domain
+print((await get_markdown(max_chars=200))["result"])
+print((await state(max_items=3))["result"])    # indexed interactive elements, model-ready
+await close_tab()
+PY
+```
+
+`state()` numbers the elements and `click_index(n)` clicks by number — the model never has to guess a CSS selector:
+
+```bash
+nekoro-browser <<'PY'
+await navigate("https://github.com/search?q=browser+automation&type=repositories")
+await wait_for_load()
+print((await state(max_items=40))["result"])
+await click_index(12)
+PY
+```
+
+All helpers are documented in [SKILL.md](SKILL.md).
+
+## MCP (Cursor / Cline / Claude Desktop)
+
+Every function in `helpers.py` is reflected into an MCP tool (45 today) — no glue code:
+
+```json
+{
+  "mcpServers": {
+    "nekoro-browser": {
+      "command": "nekoro-browser-mcp"
+    }
+  }
+}
+```
+
+The daemon still has to be running in another terminal (`nekoro-browser`) — the MCP server just forwards tool calls to it over the same authenticated path as `echo ... | nekoro-browser`. Two escape hatches ship as tools: `cdp` (raw CDP command) and `exec_python` (arbitrary Python in the daemon namespace — a whole multi-step flow in one round trip).
+
+Screenshots come back as image content so clients can render them. A helper's own failure (`{"ok": false}`) is surfaced as `isError` rather than being dressed up as success.
+
+## API
+
+| Category | Commands |
+|----------|----------|
+| Navigation | `navigate(url)`, `new_tab(url)`, `list_tabs()`, `switch_tab(id)`, `close_tab(id)` |
+| Page info | `page_info()`, `page_html()`, `page_text()`, `get_markdown()`, `state()` |
+| JavaScript | `js(code)`, `cdp(method, **p)`, `cdp_batch(*cmds)` |
+| Interaction | `click_selector(sel)`, `click_index(n)`, `click_at_xy(x,y)`, `type_text(t)`, `fill_input(sel,t)`, `press_key(k)`, `upload_file(sel,path)` |
+| Dialogs | `dialog_off()`, `get_last_dialog()` |
+| Waiting | `wait_for_load()`, `wait_selector(sel)`, `wait_for_network_idle()`, `sleep(s)` |
+| Screenshots | `capture_screenshot()`, `capture_screenshot("jpeg", 90)` |
+
+## Architecture
+
+```
+Chrome extension (background.js) —— chrome.debugger / CDP
+        ↕ persistent WebSocket
+Python daemon (127.0.0.1:28417)
+        ↕ HTTP /exec (token auth)
+CLI (nekoro-browser)  ·  MCP server (nekoro-browser-mcp)
+```
+
+`helpers.py` (46 thin wrappers) → CDP commands, each ≤10 lines, none of them aware of any particular website.
+
+`lifecycle.py` manages the daemon: pid file + process fingerprint (avoids killing a reused pid), self-heal on stale daemon (CDP probe fails → auto cleanup and restart), localhost requests bypass the system proxy.
+
+The extension is hardened against MV3 service worker eviction: a `content_scripts` heartbeat (an independent wake vector living in the page, reconnects and wakes the SW even after it's killed) + `onStartup` (reconnects instantly on Chrome cold start) + reattaches the last-driven tab after a restart instead of drifting to a blank tab.
+
+## CLI
+
+| Command | What it does |
+|---------|---------------|
+| `nekoro-browser` | Start the daemon (foreground) |
+| `nekoro-browser setup` | Guided install: extension path + opens chrome://extensions + waits for it to connect |
+| `nekoro-browser --doctor` | End-to-end diagnostic (daemon + extension + SW all alive?) |
+| `nekoro-browser --stop` | Stop the daemon |
+| `nekoro-browser --restart` | Stop and restart (foreground) |
+| `nekoro-browser --reload-ext` | Reload the extension's service worker — run before a batch job for a clean state |
+| `nekoro-browser --extension-path` | Print the extension directory (for "Load unpacked") |
+| `nekoro-browser --port N` | Run the daemon on port N (default 28417) |
+| `nekoro-browser -c "code"` | Run one snippet, print the result |
+| `nekoro-browser --timeout N` | Seconds to allow a snippet (default 120 — page loads are slow) |
+| `echo "code" \| nekoro-browser` | Pipe mode (daemon must already be running) |
+
+## Configuration
+
+The daemon listens on **28417** by default. To change it:
+
+| Side | How |
+|------|-----|
+| Python (daemon + CLI + MCP) | `nekoro-browser --port 30500`, or set `NEKORO_PORT=30500` |
+| Extension | Extension details → **Extension options** → set the port → Save (reconnects immediately, no reload) |
+
+Both sides must agree. Clients don't need the flag repeated: the daemon records its
+actual port in `<data dir>/port`, so a plain `echo ... | nekoro-browser` finds a daemon
+running on a non-default port. Precedence is `--port` > `NEKORO_PORT` > that file > default.
+
+## Self-Healing
+
+`src/nekoro_browser/agent_helpers.py` is editable at runtime and reloaded on every `/exec`. When an agent hits a gap, it appends the missing function there — effective on the next call, no daemon restart, no extension reload.
+
+`domain-skills/` is where site knowledge goes (page structure, selectors, gotchas) — Markdown only, and empty by default since everyone automates different sites. Write a workflow against your notes, drop it into `agent_helpers.py`, same convention (`daemon` as first argument). See [`domain-skills/README.md`](domain-skills/README.md).
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Windows | Primary development platform, exercised end to end |
+| Linux / macOS | The code has the branches (XDG dirs, `chmod 600` token, `/proc` and `ps` liveness probes) and CI runs the unit tests on all three, **but the full "Chrome + extension" loop has never been run on a real macOS/Linux box** — reports welcome |
+
+## Known Limitations
+
+- **Unpacked extensions get disabled by Chrome.** An extension installed via "Load unpacked" may be switched off automatically after a Chrome update or restart, or hidden behind the "Disable developer mode extensions" prompt. When `--doctor` reports Extension/SW not responding, re-enable it in `chrome://extensions/` first. This project is **not published to the Chrome Web Store**, so the limitation is not going away soon.
+- **Service worker keepalive is not 100%.** MV3 eviction timing is Chrome's call. The heartbeat + `onStartup` + reattach cover the vast majority of cases, but unattended long-running cron jobs should still health-check with `--doctor` and retry.
+- **One active tab at a time.** Tabs can be listed and switched (`list_tabs` / `switch_tab`), but commands always go to the current active tab — there are no parallel sessions.
+- **The MCP server handles requests serially.** During a `wait_selector(timeout=90)` every other request on that connection (including `ping`) queues behind it. Open separate client connections if you need concurrency.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Daemon not running` | Daemon not started | Run `nekoro-browser` in terminal 1 |
+| CDP timeout | Extension not connected / service worker asleep | `nekoro-browser --doctor` to diagnose; try `--reload-ext` or manually reload in `chrome://extensions` |
+| Extension disabled by Chrome | Unpacked extension + Chrome update | Re-enable it in `chrome://extensions/`, then re-run `--doctor` |
+| Page unchanged | Extension not attached to tab | Open a regular (non-chrome://) page, restart daemon |
+| Port in use | Stale process | Kill the process on port 28417, or just run `nekoro-browser --stop` |
+
+## Security
+
+The daemon listens on `127.0.0.1` and `/exec` runs arbitrary Python, so the transport is guarded:
+
+- **CLI / MCP → daemon** (`/exec`, `/raw`): a per-session token is written to a user-private file (`%LOCALAPPDATA%\nekoro-browser\token`, `chmod 600` on POSIX). Clients read it and send `X-Nekoro-Token`; missing/wrong token → `403`. Web pages and remote hosts can't read local files, so they can't obtain it. `/ping` stays open.
+- **Extension → daemon** (`/ws`): the handshake `Origin` must be `chrome-extension://…`; a web page's `WebSocket` to localhost carries its own origin and is rejected.
+
+Same-user local processes can read the token file — that boundary matches the OS user account, as with browser-harness's `chmod 600`.
+
+## Feedback
+
+Hit a problem, or missing a helper you need? Open an
+[issue](https://github.com/zeshuochen/nekoro-browser/issues).
+For bugs, include the output of `nekoro-browser --doctor`, your Chrome version and OS — saves a round trip.
+
+PRs welcome. Run the tests first: `for f in tests/test_*.py; do python "$f"; done` (CI runs them on all three platforms too).
+
+---
+
+## Acknowledgments
+
+Core architecture derived from:
+
+- **[browser-harness](https://github.com/browser-use/browser-harness)** — thin-wrapper philosophy (each function is a CDP alias, ≤10 lines), pipe mode, self-healing `agent_helpers.py`, domain-skills directory structure, `cdp()` raw access
+- **[browser-act](https://github.com/browser-act/skills)** — `state()` indexed element tree, `*[N]` change markers, `waitSelector()` state polling, `getMarkdown()` page extraction
+- **[Playwright](https://github.com/microsoft/playwright)** — CDP `Input.dispatchMouseEvent` real mouse events (`isTrusted:true`), extension + daemon dual-path architecture