nekoro-browser 0.3.4

Let your AI coding tool drive your own Chrome — open pages, click, read them back, still logged in everywhere.

Quick Start · Examples · Compare · MCP · API · Architecture · Site Knowledge · Limitations · Reference

nekoro-browser drives the Chrome you already use — logins, cookies, sessions, all intact.

Other automation tools spawn a fresh browser: no logins, nothing works. nekoro-browser just adds a small extension: same profile, no second instance, no "controlled by automated software" banner.

[!NOTE] Install is one uv tool install — Python stdlib only, no bundled engine, no 200MB download.

Every helper is reflected into an MCP tool (53 of them), so Claude Code, Cursor, Cline, opencode, Codex and VS Code/Copilot can drive the browser directly. Bring any model — no subscription, no lock-in. MIT, extension source included.

Quick Start

Install nekoro-browser for me:
1. `uv tool install nekoro-browser` (no uv → `pipx install nekoro-browser`).
2. Run `nekoro-browser setup` and show me the extension path it prints. This step is mine:
   I open chrome://extensions, turn on Developer mode, click Load unpacked, paste that
   path. Wait until I say it's loaded — you cannot click this for me.
3. Then start the daemon in a separate terminal that stays open: `nekoro-browser`.
4. Last step depends on how I'll use it — ask me which:
   - from my AI editor → register the MCP server (`claude mcp add nekoro-browser --
     nekoro-browser-mcp`, or the equivalent config for my client), then I restart it;
   - from the terminal only → nothing to do, `echo "page_info()" | nekoro-browser` works.
5. Finish with `nekoro-browser --doctor` and tell me if daemon / extension / service
   worker are all green.

1 — Install (Python 3.12+, zero third-party dependencies)

uv tool install nekoro-browser

No uv? pipx install nekoro-browser works too.

_{From source: git clone https://github.com/zeshuochen/nekoro-browser && cd nekoro-browser && uv pip install -e .}

[!WARNING] Upgrading? uv tool upgrade nekoro-browser only updates the Python side — reload the extension afterwards: nekoro-browser --reload-ext (or Reload on the card in chrome://extensions).

2 — Load the extension

nekoro-browser setup

Copies the extension directory to your clipboard and waits until it connects. Meanwhile: chrome://extensions/ → Developer mode → Load unpacked → paste.

3 — Start the daemon — open a second terminal and leave it running (it's the background process that holds the Chrome connection; close it and everything stops)

nekoro-browser

4 — Drive the browser. Pick the way you actually work:

From your AI coding tool (MCP) — one command for Claude Code, other clients in MCP:

claude mcp add nekoro-browser -- nekoro-browser-mcp

Restart the client and ask it to open a page. That's it — 53 browser tools show up.

From the terminal — pipe a snippet to the running daemon:

echo "page_info()" | nekoro-browser
# → {"ok": true, "result": {"title": "...", "url": "..."}}

Something down? nekoro-browser --doctor checks daemon / extension / service worker and tells you which one.

Examples

Send a multi-step flow in one shot. Every helper is already await-able at top level — no asyncio boilerplate, no imports:

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

@'
await new_tab("https://example.com")
print((await page_info())["title"])
'@ | nekoro-browser

state() numbers the elements and click_index(n) clicks by number — the model never has to guess a CSS selector:

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"])   # every interactive element carries an index
PY

Then click the one you saw — indices shift with page content, so don't copy a fixed number:

nekoro-browser -c "await click_index(7)"

All helpers are documented in SKILL.md.

How It Compares

_{Why row 3 is ❌: since Chrome 136, --remote-debugging-port refuses the default profile — a raw CDP connection means a fresh instance with none of your logins. An extension's chrome.debugger is exempt.}

MCP (any MCP client)

MCP is how Claude Code, Cursor and friends call outside tools. Hook it up once and the model gets navigate, click_index, get_markdown… as first-class tools.

Prerequisite: the daemon is running (nekoro-browser, its own terminal) — the MCP server is a thin forwarder, the daemon owns the Chrome connection.

The command to register is always nekoro-browser-mcp. Only the config shape differs:

Claude Code

claude mcp add nekoro-browser -- nekoro-browser-mcp

Claude Desktop (Settings → Developer → Edit Config) · Cursor (~/.cursor/mcp.json, or .cursor/mcp.json for one project) · Cline (MCP Servers → Configure MCP Servers)

{ "mcpServers": { "nekoro-browser": { "command": "nekoro-browser-mcp" } } }

_{Claude Desktop config file: macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json}

opencode (opencode.json) — note command is an array, and the key is mcp

{ "mcp": { "nekoro-browser": { "type": "local", "command": ["nekoro-browser-mcp"], "enabled": true } } }

Codex (~/.codex/config.toml, or codex mcp add nekoro-browser -- nekoro-browser-mcp)

[mcp_servers.nekoro-browser]
command = "nekoro-browser-mcp"

VS Code / Copilot (.vscode/mcp.json, or MCP: Open User Configuration) — the key is servers, not mcpServers

{ "servers": { "nekoro-browser": { "command": "nekoro-browser-mcp" } } }

Prefer not to install anything up front? Replace the command with uvx, which fetches and runs on demand the way npx -y does — e.g. "command": "uvx", "args": ["--from", "nekoro-browser", "nekoro-browser-mcp"]. That only removes the install step for the MCP server; the daemon still has to be installed and running.

Restart the client afterwards. If the tools don't show up, run nekoro-browser --doctor first — a dead daemon looks exactly like a broken MCP config — then check the client's MCP log (Claude Desktop keeps them in ~/Library/Logs/Claude on macOS, %APPDATA%\Claude\logs on Windows).

Beyond the tool list:

• cdp — raw CDP command, and exec_python — arbitrary Python in the daemon namespace, so a whole multi-step flow costs one round trip.
• Screenshots return as image content; clients render them inline.
• A helper failure ({"ok": false}) surfaces as isError, never dressed up as success.
• Navigating to a site you have notes or scripts for ships them in the tool result — see Site Knowledge.

API

_{All page-level helpers take an optional tab= (default: the active tab). capture_screenshot defaults to scale="css" — pixel size equals the CSS viewport, so coordinates can be fed straight to click_at_xy; scale="device" keeps physical pixels.}

Architecture

flowchart TD
    A["Chrome tab — your profile, your logins"]
    B["Extension background.js<br/>chrome.debugger / CDP"]
    C["Python daemon<br/>127.0.0.1:28417"]
    D["CLI<br/>nekoro-browser"]
    E["MCP server<br/>nekoro-browser-mcp"]

    A <-->|CDP| B
    B <-->|persistent WebSocket| C
    D -->|"HTTP /exec · token auth"| C
    E -->|"HTTP /exec · token auth"| C

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 — 54 helpers (53 exposed as MCP tools), none aware of any particular website.
• lifecycle.py — pid file + process fingerprint (never kills a reused pid), stale-daemon self-heal (CDP probe fails → cleanup and restart), localhost bypasses the system proxy.
• Extension, against MV3 service worker eviction — content_scripts heartbeat (wake vector living in the page, revives a killed SW) + onStartup (reconnects on Chrome cold start) + reattaches the last-driven tab instead of drifting to a blank one.

Self-Healing and Site Knowledge

When an agent hits a gap it writes the missing piece and uses it immediately — nothing is recompiled, no daemon restart, no extension reload.

• src/nekoro_browser/agent_helpers.py is scratch paper: reloaded on every /exec, good for a quick experiment. It lives inside the installed package, so an upgrade overwrites it.
• Anything worth keeping goes in your own skills directory (NEKORO_DOMAIN_SKILLS, falling back to domain-skills/ in the repo), one folder per site holding both kinds of material: <site>/*.md for knowledge and <site>/*.py for workflows. Scripts are loaded into the /exec namespace on every call and can use the built-in helpers directly.

The point is that this material finds the agent instead of waiting to be discovered. navigate() and new_tab() return two extra fields when the site has any:

{'ok': True, 'loaded': True,
 'notes':   ['example/search.md — Example — search results'],
 'actions': ['open_first_result(query) — search and open the top hit']}

notes lists titles only; actions lists functions that are already callable, so the agent runs one instead of rebuilding the flow. list_site_actions() shows everything loaded, failed files included. What to record — and what not to — is in domain-skills/README.md.

Tabs work the same way: a tab left over from last time still holds its login and page state, so new_tab() adds an existing field when the managed group already has tabs for that site:

{'ok': True, 'tabId': 42, 'loaded': True,
 'existing': {'hint': 'switch_tab(id) reuses an open tab, or new_tab(url, reuse=True)',
              'tabs': [{'tabId': 17, 'title': 'Example Domain'}]}}

The tab still opens — the field only makes reuse visible at the moment a duplicate is about to appear; reuse=True navigates the existing one instead. Nothing is ever closed automatically: sweep_tabs() only reports candidates (same-site duplicates, stray about:blank), sweep_tabs(dry_run=False) / close_tabs([...]) act on them, and the active tab is never a candidate.

Platform Support

_{Linux/macOS have the platform branches (~/.config / ~/Library/Application Support data dirs, chmod 600 token, /proc + ps liveness probes) and CI runs unit tests on all three — but the full "Chrome + extension" loop has never run on a real macOS/Linux box.}

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.
• Everything is anchored to one active tab. 16 helpers (click, click_selector, state, wait_selector, fill_input, …) take an explicit tab=id to target another already attached tab — naming a tab that is not attached is an error, never a silent fallback to the active one. The other 37 always follow the active tab, and there are still no parallel sessions: one daemon drives one Chrome, requests are serialised.
• Downloads land wherever Chrome is configured to put them; the path cannot be changed from here. wait_for_download() returns {url, filename, bytes} — a filename, not a full path. Set the directory in Chrome's own settings. _{Both Browser.setDownloadBehavior (-32601) and the deprecated Page.setDownloadBehavior (-32000 "Cannot not access browser-level commands") are browser-level and get rejected under chrome.debugger, which only ever hands out a tab target.}
• 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.

Reference

Feedback

Hit a problem, or missing a helper you need? Open an issue. 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 uv run python "$f"; done (CI runs them on all three platforms too).

Acknowledgments

Core architecture derived from:

• 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 — state() indexed element tree, *[N] change markers, waitSelector() state polling, getMarkdown() page extraction
• Playwright — CDP Input.dispatchMouseEvent real mouse events (isTrusted:true), extension + daemon dual-path architecture

Ideas drawn from:

• ego-lite — "code base, not CLI base" (agent writes a script, not a command loop), unified locator syntax (css: / text: / xpath= …) with transient/permanent element-resolution errors as a retry/abandon signal (→ click()), "name says the intent" openOrReuseTab ergonomics (→ ensure_tab()), and experience-accumulation as a first-class design goal (nekoro's domain-skills already chase this)