kitsune-browser 0.7.0__tar.gz

kitsune_browser-0.7.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+web-ext-artifacts/
+build/
+*.xpi
+kitsune-extension-*.zip

kitsune_browser-0.7.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jay-Quan (ZenLink, ZenLink-MCP)
+Copyright (c) 2026 junyeong-nero (Kitsune)
+
+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.

kitsune_browser-0.7.0/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.5
+Name: kitsune-browser
+Version: 0.7.0
+Summary: Drive the Firefox, Zen, or LibreWolf browser you already have open from Python or an AI agent.
+Project-URL: Homepage, https://github.com/junyeong-nero/kitsune
+Project-URL: Documentation, https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md
+Project-URL: Issues, https://github.com/junyeong-nero/kitsune/issues
+Project-URL: Changelog, https://github.com/junyeong-nero/kitsune/releases
+Author: junyeong-nero
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,browser-automation,firefox,mcp,zen-browser
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: websockets>=14.2
+Provides-Extra: macos
+Requires-Dist: pyobjc-framework-quartz>=10; (sys_platform == 'darwin') and extra == 'macos'
+Provides-Extra: mcp
+Requires-Dist: mcp[cli]<2,>=1.2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Kitsune
+
+<!-- mcp-name: io.github.junyeong-nero/kitsune -->
+
+![Kitsune: an orange fox in a browser window, connecting your browser and your AI agent](https://raw.githubusercontent.com/junyeong-nero/kitsune/main/assets/kitsune-hero.svg)
+
+[![PyPI](https://img.shields.io/pypi/v/kitsune-browser-mcp)](https://pypi.org/project/kitsune-browser-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/kitsune-browser-mcp)](https://pypi.org/project/kitsune-browser-mcp/)
+[![Release](https://img.shields.io/github/v/release/junyeong-nero/kitsune)](https://github.com/junyeong-nero/kitsune/releases/latest)
+[![License: MIT](https://img.shields.io/github/license/junyeong-nero/kitsune)](https://github.com/junyeong-nero/kitsune/blob/main/LICENSE)
+
+**Bring your coding agent into Firefox and keep working alongside it.**
+
+Kitsune lets AI agents such as Claude Code, Codex, Pi, and OpenCode use the Firefox,
+Zen, or LibreWolf browser you already have open. Your sessions, cookies, and
+extensions stay where they are, and there is no Playwright, Chromium, or WebDriver
+to install.
+
+The agent can research in background tabs and prepare form drafts while you keep
+using the same browser. You stay with the agent you already use; Kitsune is not a
+separate browser or a built-in assistant.
+
+The design follows two principles: the user's browser belongs to the user, and
+the agent gets fewer, sharper tools. See [Philosophy](https://github.com/junyeong-nero/kitsune/blob/main/docs/philosophy.md).
+
+![Claude Code uses Kitsune to search Google Flights and Google Maps in background Zen tabs for a weekend in Tokyo, booking nothing, while the user's Google tab stays in front](https://raw.githubusercontent.com/junyeong-nero/kitsune/main/assets/demo.gif)
+
+<sub>A real screen recording of Claude Code and Zen Browser on the live Google sites, sped up while the agent thinks and zoomed in afterwards (<a href="https://github.com/user-attachments/assets/9b61f335-073d-4035-b479-ee03e96ae202">full 38-second video</a>).</sub>
+
+## Why Kitsune?
+
+- Tabs the agent creates open in the background. Kitsune holds writes to a tab
+  you are actively using, and closing one of your own tabs takes a separate
+  confirmation step. This reduces interference, but OS-level clicks and popups
+  opened by sites still have [focus and input limitations](https://github.com/junyeong-nero/kitsune/blob/main/docs/api-reference.md#shared-browser).
+- You decide how much to delegate. `KITSUNE_MODE=read`, `draft`, or `act` limits
+  both the tools the agent sees and the requests the bridge accepts. Draft mode
+  lets the agent fill supported fields without click or submit tools, although
+  sites may still autosave what it types. The default, `act`, has no such
+  restriction. See [Task modes](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#task-modes).
+- The agent starts with Playwright MCP's 25 core tools. Kitsune's other tools
+  stay off until you allow them, and the agent can find and call the allowed ones
+  without restarting its session. See [Choosing tools](https://github.com/junyeong-nero/kitsune#choosing-tools).
+- With the optional `automation` capability, an interrupted batch, parallel, or
+  workflow call can be resumed without resending the writes that already
+  succeeded. A write with an uncertain outcome needs an observation before it is
+  retried. [Checkpoints](https://github.com/junyeong-nero/kitsune/blob/main/docs/checkpoint-resume.md) are temporary and are lost when the bridge restarts.
+
+## What can it do?
+
+In your browser, the agent can:
+
+- Search the web, read pages, and summarize what it finds with links.
+- Click, type, select options, and fill forms, including on sites where you are
+  already signed in.
+- Take screenshots or turn page content into text and Markdown.
+- Keep research and tasks in separate tabs without replacing the page you are
+  using.
+
+## Benchmark
+
+![Kitsune v0.4.0 vs Playwright MCP 0.0.83: kept the user's tab in front in 23 of 24 tasks vs 2 of 24; 0.83 to 0.93 times the cost on tasks both solved; 191 of 198 vs 197 of 198 tasks solved](https://raw.githubusercontent.com/junyeong-nero/kitsune/main/assets/benchmark.png)
+
+With the same tasks and tool allowlist, Kitsune v0.4.0 kept the user's tab in
+front in 23 of 24 shared-browser tasks, against 2 of 24 for Playwright MCP. On
+the tasks both solved, Kitsune cost 0.83 to 0.93 times as much. It solved 191 of
+198 tasks, and Playwright MCP solved 197. Each task was run once with Claude Opus
+5.5. Playwright MCP was not designed to share a browser with a person. See the
+[full reports](https://github.com/junyeong-nero/kitsune-benchmark/tree/main/docs/results).
+
+## How is it different?
+
+Kitsune is one of several ways to connect an agent to a browser. Which one fits
+depends on the browser you use and the work you want to hand off:
+
+| If you want to… | Consider |
+| --- | --- |
+| Delegate tasks in the Firefox-family browser you are using, with background tabs, read/draft/act modes, and resumable batches | **Kitsune** |
+| Debug or profile pages in Firefox (debugger, profiler, deep protocol access) | [Mozilla Firefox DevTools MCP](https://github.com/mozilla/firefox-devtools-mcp), which attaches to a running Firefox started with remote-debugging flags |
+| Test across Chromium, Firefox, and WebKit in launched browsers | [Playwright MCP](https://github.com/microsoft/playwright-mcp); Kitsune publishes its 25 core tools, so prompts written for it carry over |
+| Drive the Chrome you already use | A Chromium extension MCP such as [Browser MCP](https://github.com/BrowserMCP/mcp) |
+
+Kitsune connects through an extension and a local bridge, so Firefox needs no
+startup flags or WebDriver. Other Firefox extension projects also reuse your
+logins. Kitsune concentrates on sharing the browser with you while the agent
+works. [Positioning](https://github.com/junyeong-nero/kitsune/blob/main/docs/positioning.md)
+has the full comparison and its limits.
+
+## How do I use it?
+
+1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then
+   follow the [MCP setup](#mcp-setup) for your agent below.
+   [Install the browser extension](https://github.com/junyeong-nero/kitsune/blob/main/docs/installation.md#2-install-the-browser-extension)
+   in Firefox, Zen, or LibreWolf. The signed build stays installed; the
+   developer build, which `browser_evaluate` needs, is a temporary add-on.
+2. Keep the browser open. Kitsune starts its shared bridge automatically. Before
+   your first task, ask the agent to check the connection.
+3. Ask in plain language. For example:
+
+   > Research these three products in new background tabs and compare them with
+   > source links. Leave my current tab alone.
+
+   > Inspect this page's form and fill a draft. Don't submit it yet.
+
+   > Open Hacker News in a background tab and summarize the top three stories
+   > with links.
+
+   Asking in plain language does not change the mode. To enforce a draft-only
+   tool set, set `KITSUNE_MODE=draft` before starting the MCP client.
+
+Use a dedicated browser profile, and give the agent access only to the accounts
+it needs. Have it ask you before it sends, buys, or deletes anything. The opt-in
+[ask-before-act](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#ask-before-act)
+policy makes the bridge hold submits, payment pages, JavaScript, and cookie access
+until the agent repeats the call with a confirmation token. The agent can make
+that second call on its own, so it does not prove that a person approved, and
+none of these controls prevent prompt injection. Read the [security guidance](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#security) before using sensitive accounts.
+
+## MCP setup
+
+Every client launches the same local stdio server:
+`uvx --from kitsune-browser-mcp kitsune`. Use only one setup method per client.
+Several clients can share one bridge; keep them on the same Kitsune version and
+install source.
+
+### CLI registration: Claude Code, Codex, and Pi
+
+**Claude Code**, available in every project with `--scope user`:
+
+```bash
+claude mcp add --scope user kitsune -- uvx --from kitsune-browser-mcp kitsune
+```
+
+**Codex CLI**, which registers the server in `~/.codex/config.toml`:
+
+```bash
+codex mcp add kitsune -- uvx --from kitsune-browser-mcp kitsune
+```
+
+**Pi** has [built-in MCP support](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md)
+and registers servers for your user by default:
+
+```bash
+pi mcp add kitsune -- uvx --from kitsune-browser-mcp kitsune
+pi mcp list
+```
+
+To register the server only for the current project, add `--local` before
+`kitsune`. In a Pi session that is already running, run `/reload`, then `/mcp` to
+check the connection. If an MCP adapter extension replaces Pi's built-in support,
+follow that extension's instructions instead.
+
+### OpenCode
+
+Merge this into `~/.config/opencode/opencode.json` (global) or `opencode.json`
+in your project root. OpenCode uses an `mcp` object with a command array, not
+`mcpServers`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "kitsune": {
+      "type": "local",
+      "command": ["uvx", "--from", "kitsune-browser-mcp", "kitsune"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### JSON configuration: Pi, Claude Desktop, and Cursor
+
+These clients use the same `mcpServers` format. Instead of CLI registration,
+where a client has it, you can merge this entry into the client's config file
+and keep any servers already there:
+
+| Client | Config file |
+| --- | --- |
+| Pi (built-in MCP) | `~/.pi/agent/mcp.json` (user) or `.pi/mcp.json` (project; requires project trust) |
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |
+
+```json
+{
+  "mcpServers": {
+    "kitsune": {
+      "command": "uvx",
+      "args": ["--from", "kitsune-browser-mcp", "kitsune"]
+    }
+  }
+}
+```
+
+After configuring a client, restart or reconnect it and ask it to list your tabs
+(`browser_tabs` with `action: "list"`). If that fails, the error's `hint` says
+what to fix. A GUI app that does not inherit your shell's `PATH` may need the
+full path from `which uvx` in place of `uvx`.
+
+### Choosing tools
+
+By default Kitsune publishes [Playwright MCP](https://github.com/microsoft/playwright-mcp)'s
+25 core tools with the same names, descriptions, and schemas, and they drive your
+own browser. Prompts and clients written for Playwright MCP work unchanged
+([Core tools](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#core-tools)). Kitsune's own tools are sorted into capability groups,
+which you enable with `KITSUNE_CAPS` in the MCP server's environment:
+
+| Group | Tools for |
+| --- | --- |
+| `browse` | Scrolling, forward navigation, checkboxes, focus, form submits, trusted OS clicks |
+| `read` | Page text and Markdown, forms, DOM, links, images, metadata |
+| `inspect` | Element bounds, computed styles, selector diagnosis, highlights |
+| `tabs` | Pinning, muting, zoom, windows, tab tags, keep-alive |
+| `automation` | Batches, retries, workflows, parallel tabs, resume |
+| `network` | Downloads, request interception and capture |
+| `admin` | Connection status, logs, audit, cache, policy |
+| `storage`, `history` | Cookies, page storage, clipboard and saved sessions; history and bookmarks. They read personal data, so `all` leaves them out and you enable them by name |
+
+You can allow more tools than you publish, which keeps the agent's starting tool
+list small. With `KITSUNE_CAPS=all` and `KITSUNE_PUBLISH=core`, the agent starts
+with the core tools and can find and call the others in the same session
+([Finding tools without a restart](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#finding-tools-without-a-restart)). With Claude Code, for
+example:
+
+```bash
+claude mcp add --scope user kitsune -e KITSUNE_CAPS=all -e KITSUNE_PUBLISH=core -- uvx --from kitsune-browser-mcp kitsune
+```
+
+In the JSON configurations above, add `"env": {"KITSUNE_CAPS": "all", "KITSUNE_PUBLISH": "core"}`
+next to `"args"`. The bridge checks the groups on every request, including batch
+steps. A tool called without a tab acts on the agent's current tab, not the one
+you are looking at.
+
+If you are upgrading from 0.3: the `devtools`, `parallel`, `windows` and `session`
+groups were replaced by the groups above, and `all` no longer includes `storage`.
+A configuration that names a removed group fails at startup. [Tools](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#tools) lists
+where each tool went.
+
+[Installation](https://github.com/junyeong-nero/kitsune/blob/main/docs/installation.md) covers Codex's TOML configuration, environment
+variables, version pinning, and upgrades.
+
+More documentation: [Tools](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#tools) ·
+[Configuration](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#configuration) ·
+[Troubleshooting](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#troubleshooting) ·
+[Updating](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#updating-kitsune) ·
+[API reference](https://github.com/junyeong-nero/kitsune/blob/main/docs/api-reference.md) ·
+[Python API](https://github.com/junyeong-nero/kitsune/blob/main/docs/python-api.md) ·
+[Development](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#development) ·
+[FAQ](https://github.com/junyeong-nero/kitsune/blob/main/docs/faq.md)
+
+The architecture, product trade-offs, and comparisons with other browser MCP
+servers are in [Positioning](https://github.com/junyeong-nero/kitsune/blob/main/docs/positioning.md).
+
+## Python API
+
+The same extension and bridge also work from your own code. The code is the
+`kitsune-browser` package, which the MCP server's package installs with the server;
+`pip install kitsune-browser` alone gives you a Python API with every capability group,
+storage and history included:
+
+```python
+import kitsune
+
+browser = kitsune.connect()                        # starts the bridge if none runs
+tab = browser.new_tab("https://news.ycombinator.com")   # a background tab you don't see
+for link in tab.query(".titleline > a", fields=["text", "href"], limit=3):
+    print(link["text"], link["href"])
+tab.close()
+```
+
+The MCP server limits what an agent sees; the Python API does not, but the bridge's
+shared-browser rules hold for both: tabs open in the background, your own tabs close
+only with your approval, and sensitive fields stay redacted. `kitsune.connect(confirm=...)`
+lets a person approve each action that needs it. See [Python API](https://github.com/junyeong-nero/kitsune/blob/main/docs/python-api.md).

kitsune_browser-0.7.0/README.md

@@ -0,0 +1,274 @@
+# Kitsune
+
+<!-- mcp-name: io.github.junyeong-nero/kitsune -->
+
+![Kitsune: an orange fox in a browser window, connecting your browser and your AI agent](https://raw.githubusercontent.com/junyeong-nero/kitsune/main/assets/kitsune-hero.svg)
+
+[![PyPI](https://img.shields.io/pypi/v/kitsune-browser-mcp)](https://pypi.org/project/kitsune-browser-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/kitsune-browser-mcp)](https://pypi.org/project/kitsune-browser-mcp/)
+[![Release](https://img.shields.io/github/v/release/junyeong-nero/kitsune)](https://github.com/junyeong-nero/kitsune/releases/latest)
+[![License: MIT](https://img.shields.io/github/license/junyeong-nero/kitsune)](https://github.com/junyeong-nero/kitsune/blob/main/LICENSE)
+
+**Bring your coding agent into Firefox and keep working alongside it.**
+
+Kitsune lets AI agents such as Claude Code, Codex, Pi, and OpenCode use the Firefox,
+Zen, or LibreWolf browser you already have open. Your sessions, cookies, and
+extensions stay where they are, and there is no Playwright, Chromium, or WebDriver
+to install.
+
+The agent can research in background tabs and prepare form drafts while you keep
+using the same browser. You stay with the agent you already use; Kitsune is not a
+separate browser or a built-in assistant.
+
+The design follows two principles: the user's browser belongs to the user, and
+the agent gets fewer, sharper tools. See [Philosophy](https://github.com/junyeong-nero/kitsune/blob/main/docs/philosophy.md).
+
+![Claude Code uses Kitsune to search Google Flights and Google Maps in background Zen tabs for a weekend in Tokyo, booking nothing, while the user's Google tab stays in front](https://raw.githubusercontent.com/junyeong-nero/kitsune/main/assets/demo.gif)
+
+<sub>A real screen recording of Claude Code and Zen Browser on the live Google sites, sped up while the agent thinks and zoomed in afterwards (<a href="https://github.com/user-attachments/assets/9b61f335-073d-4035-b479-ee03e96ae202">full 38-second video</a>).</sub>
+
+## Why Kitsune?
+
+- Tabs the agent creates open in the background. Kitsune holds writes to a tab
+  you are actively using, and closing one of your own tabs takes a separate
+  confirmation step. This reduces interference, but OS-level clicks and popups
+  opened by sites still have [focus and input limitations](https://github.com/junyeong-nero/kitsune/blob/main/docs/api-reference.md#shared-browser).
+- You decide how much to delegate. `KITSUNE_MODE=read`, `draft`, or `act` limits
+  both the tools the agent sees and the requests the bridge accepts. Draft mode
+  lets the agent fill supported fields without click or submit tools, although
+  sites may still autosave what it types. The default, `act`, has no such
+  restriction. See [Task modes](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#task-modes).
+- The agent starts with Playwright MCP's 25 core tools. Kitsune's other tools
+  stay off until you allow them, and the agent can find and call the allowed ones
+  without restarting its session. See [Choosing tools](https://github.com/junyeong-nero/kitsune#choosing-tools).
+- With the optional `automation` capability, an interrupted batch, parallel, or
+  workflow call can be resumed without resending the writes that already
+  succeeded. A write with an uncertain outcome needs an observation before it is
+  retried. [Checkpoints](https://github.com/junyeong-nero/kitsune/blob/main/docs/checkpoint-resume.md) are temporary and are lost when the bridge restarts.
+
+## What can it do?
+
+In your browser, the agent can:
+
+- Search the web, read pages, and summarize what it finds with links.
+- Click, type, select options, and fill forms, including on sites where you are
+  already signed in.
+- Take screenshots or turn page content into text and Markdown.
+- Keep research and tasks in separate tabs without replacing the page you are
+  using.
+
+## Benchmark
+
+![Kitsune v0.4.0 vs Playwright MCP 0.0.83: kept the user's tab in front in 23 of 24 tasks vs 2 of 24; 0.83 to 0.93 times the cost on tasks both solved; 191 of 198 vs 197 of 198 tasks solved](https://raw.githubusercontent.com/junyeong-nero/kitsune/main/assets/benchmark.png)
+
+With the same tasks and tool allowlist, Kitsune v0.4.0 kept the user's tab in
+front in 23 of 24 shared-browser tasks, against 2 of 24 for Playwright MCP. On
+the tasks both solved, Kitsune cost 0.83 to 0.93 times as much. It solved 191 of
+198 tasks, and Playwright MCP solved 197. Each task was run once with Claude Opus
+5.5. Playwright MCP was not designed to share a browser with a person. See the
+[full reports](https://github.com/junyeong-nero/kitsune-benchmark/tree/main/docs/results).
+
+## How is it different?
+
+Kitsune is one of several ways to connect an agent to a browser. Which one fits
+depends on the browser you use and the work you want to hand off:
+
+| If you want to… | Consider |
+| --- | --- |
+| Delegate tasks in the Firefox-family browser you are using, with background tabs, read/draft/act modes, and resumable batches | **Kitsune** |
+| Debug or profile pages in Firefox (debugger, profiler, deep protocol access) | [Mozilla Firefox DevTools MCP](https://github.com/mozilla/firefox-devtools-mcp), which attaches to a running Firefox started with remote-debugging flags |
+| Test across Chromium, Firefox, and WebKit in launched browsers | [Playwright MCP](https://github.com/microsoft/playwright-mcp); Kitsune publishes its 25 core tools, so prompts written for it carry over |
+| Drive the Chrome you already use | A Chromium extension MCP such as [Browser MCP](https://github.com/BrowserMCP/mcp) |
+
+Kitsune connects through an extension and a local bridge, so Firefox needs no
+startup flags or WebDriver. Other Firefox extension projects also reuse your
+logins. Kitsune concentrates on sharing the browser with you while the agent
+works. [Positioning](https://github.com/junyeong-nero/kitsune/blob/main/docs/positioning.md)
+has the full comparison and its limits.
+
+## How do I use it?
+
+1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then
+   follow the [MCP setup](#mcp-setup) for your agent below.
+   [Install the browser extension](https://github.com/junyeong-nero/kitsune/blob/main/docs/installation.md#2-install-the-browser-extension)
+   in Firefox, Zen, or LibreWolf. The signed build stays installed; the
+   developer build, which `browser_evaluate` needs, is a temporary add-on.
+2. Keep the browser open. Kitsune starts its shared bridge automatically. Before
+   your first task, ask the agent to check the connection.
+3. Ask in plain language. For example:
+
+   > Research these three products in new background tabs and compare them with
+   > source links. Leave my current tab alone.
+
+   > Inspect this page's form and fill a draft. Don't submit it yet.
+
+   > Open Hacker News in a background tab and summarize the top three stories
+   > with links.
+
+   Asking in plain language does not change the mode. To enforce a draft-only
+   tool set, set `KITSUNE_MODE=draft` before starting the MCP client.
+
+Use a dedicated browser profile, and give the agent access only to the accounts
+it needs. Have it ask you before it sends, buys, or deletes anything. The opt-in
+[ask-before-act](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#ask-before-act)
+policy makes the bridge hold submits, payment pages, JavaScript, and cookie access
+until the agent repeats the call with a confirmation token. The agent can make
+that second call on its own, so it does not prove that a person approved, and
+none of these controls prevent prompt injection. Read the [security guidance](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#security) before using sensitive accounts.
+
+## MCP setup
+
+Every client launches the same local stdio server:
+`uvx --from kitsune-browser-mcp kitsune`. Use only one setup method per client.
+Several clients can share one bridge; keep them on the same Kitsune version and
+install source.
+
+### CLI registration: Claude Code, Codex, and Pi
+
+**Claude Code**, available in every project with `--scope user`:
+
+```bash
+claude mcp add --scope user kitsune -- uvx --from kitsune-browser-mcp kitsune
+```
+
+**Codex CLI**, which registers the server in `~/.codex/config.toml`:
+
+```bash
+codex mcp add kitsune -- uvx --from kitsune-browser-mcp kitsune
+```
+
+**Pi** has [built-in MCP support](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md)
+and registers servers for your user by default:
+
+```bash
+pi mcp add kitsune -- uvx --from kitsune-browser-mcp kitsune
+pi mcp list
+```
+
+To register the server only for the current project, add `--local` before
+`kitsune`. In a Pi session that is already running, run `/reload`, then `/mcp` to
+check the connection. If an MCP adapter extension replaces Pi's built-in support,
+follow that extension's instructions instead.
+
+### OpenCode
+
+Merge this into `~/.config/opencode/opencode.json` (global) or `opencode.json`
+in your project root. OpenCode uses an `mcp` object with a command array, not
+`mcpServers`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "kitsune": {
+      "type": "local",
+      "command": ["uvx", "--from", "kitsune-browser-mcp", "kitsune"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### JSON configuration: Pi, Claude Desktop, and Cursor
+
+These clients use the same `mcpServers` format. Instead of CLI registration,
+where a client has it, you can merge this entry into the client's config file
+and keep any servers already there:
+
+| Client | Config file |
+| --- | --- |
+| Pi (built-in MCP) | `~/.pi/agent/mcp.json` (user) or `.pi/mcp.json` (project; requires project trust) |
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |
+
+```json
+{
+  "mcpServers": {
+    "kitsune": {
+      "command": "uvx",
+      "args": ["--from", "kitsune-browser-mcp", "kitsune"]
+    }
+  }
+}
+```
+
+After configuring a client, restart or reconnect it and ask it to list your tabs
+(`browser_tabs` with `action: "list"`). If that fails, the error's `hint` says
+what to fix. A GUI app that does not inherit your shell's `PATH` may need the
+full path from `which uvx` in place of `uvx`.
+
+### Choosing tools
+
+By default Kitsune publishes [Playwright MCP](https://github.com/microsoft/playwright-mcp)'s
+25 core tools with the same names, descriptions, and schemas, and they drive your
+own browser. Prompts and clients written for Playwright MCP work unchanged
+([Core tools](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#core-tools)). Kitsune's own tools are sorted into capability groups,
+which you enable with `KITSUNE_CAPS` in the MCP server's environment:
+
+| Group | Tools for |
+| --- | --- |
+| `browse` | Scrolling, forward navigation, checkboxes, focus, form submits, trusted OS clicks |
+| `read` | Page text and Markdown, forms, DOM, links, images, metadata |
+| `inspect` | Element bounds, computed styles, selector diagnosis, highlights |
+| `tabs` | Pinning, muting, zoom, windows, tab tags, keep-alive |
+| `automation` | Batches, retries, workflows, parallel tabs, resume |
+| `network` | Downloads, request interception and capture |
+| `admin` | Connection status, logs, audit, cache, policy |
+| `storage`, `history` | Cookies, page storage, clipboard and saved sessions; history and bookmarks. They read personal data, so `all` leaves them out and you enable them by name |
+
+You can allow more tools than you publish, which keeps the agent's starting tool
+list small. With `KITSUNE_CAPS=all` and `KITSUNE_PUBLISH=core`, the agent starts
+with the core tools and can find and call the others in the same session
+([Finding tools without a restart](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#finding-tools-without-a-restart)). With Claude Code, for
+example:
+
+```bash
+claude mcp add --scope user kitsune -e KITSUNE_CAPS=all -e KITSUNE_PUBLISH=core -- uvx --from kitsune-browser-mcp kitsune
+```
+
+In the JSON configurations above, add `"env": {"KITSUNE_CAPS": "all", "KITSUNE_PUBLISH": "core"}`
+next to `"args"`. The bridge checks the groups on every request, including batch
+steps. A tool called without a tab acts on the agent's current tab, not the one
+you are looking at.
+
+If you are upgrading from 0.3: the `devtools`, `parallel`, `windows` and `session`
+groups were replaced by the groups above, and `all` no longer includes `storage`.
+A configuration that names a removed group fails at startup. [Tools](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#tools) lists
+where each tool went.
+
+[Installation](https://github.com/junyeong-nero/kitsune/blob/main/docs/installation.md) covers Codex's TOML configuration, environment
+variables, version pinning, and upgrades.
+
+More documentation: [Tools](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#tools) ·
+[Configuration](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#configuration) ·
+[Troubleshooting](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#troubleshooting) ·
+[Updating](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#updating-kitsune) ·
+[API reference](https://github.com/junyeong-nero/kitsune/blob/main/docs/api-reference.md) ·
+[Python API](https://github.com/junyeong-nero/kitsune/blob/main/docs/python-api.md) ·
+[Development](https://github.com/junyeong-nero/kitsune/blob/main/docs/guide.md#development) ·
+[FAQ](https://github.com/junyeong-nero/kitsune/blob/main/docs/faq.md)
+
+The architecture, product trade-offs, and comparisons with other browser MCP
+servers are in [Positioning](https://github.com/junyeong-nero/kitsune/blob/main/docs/positioning.md).
+
+## Python API
+
+The same extension and bridge also work from your own code. The code is the
+`kitsune-browser` package, which the MCP server's package installs with the server;
+`pip install kitsune-browser` alone gives you a Python API with every capability group,
+storage and history included:
+
+```python
+import kitsune
+
+browser = kitsune.connect()                        # starts the bridge if none runs
+tab = browser.new_tab("https://news.ycombinator.com")   # a background tab you don't see
+for link in tab.query(".titleline > a", fields=["text", "href"], limit=3):
+    print(link["text"], link["href"])
+tab.close()
+```
+
+The MCP server limits what an agent sees; the Python API does not, but the bridge's
+shared-browser rules hold for both: tabs open in the background, your own tabs close
+only with your approval, and sensitive fields stay redacted. `kitsune.connect(confirm=...)`
+lets a person approve each action that needs it. See [Python API](https://github.com/junyeong-nero/kitsune/blob/main/docs/python-api.md).