Skip to main content
Glama
README.md
# K-Browser

[繁體中文](README.zh-TW.md)

Let the agents on your Mac (Claude Code, Codex, Antigravity, Gemini CLI) use **your own Chrome**: the one you are already
signed in to, in a window you can watch.

An agent only sees and controls **the tabs it opened itself**. Your other tabs are never listed, read or touched.

## How it works

```
 Claude Code ─┐                                         ┌──────────────────────────────┐
 Codex ───────┤ MCP (stdio)     ┌──────────────────┐    │ Your Chrome                  │
 Antigravity ─┼───────────────▶ │ Bridge           │◀──▶│  K-Browser extension         │
 Gemini CLI ──┘  one token each │ 127.0.0.1:9444   │ ws │  (chrome.debugger on the     │
                                │ (LaunchAgent)    │    │   agents' own tabs only)     │
 Kav ───────────────────────────▶ CDP endpoint     │    └──────────────────────────────┘
                 its own token  └──────────────────┘
```

- **Bridge**: a small Node.js service on `127.0.0.1:9444`, started at login by a macOS LaunchAgent. It checks who is
  asking, enforces each client's policy, masks secrets and keeps the activity log.
- **Chrome extension**: runs in your Chrome and works the agents' tabs for the bridge. It only connects to the bridge after
  you pair it with a pairing code.
- **MCP server**: one per agent, each with its own token and its own permissions.

## What keeps you in control

- **Ownership.** Every tab belongs to the client that opened it (popups it opens too). A client cannot list, read or act
  on anything else.
- **Never steals focus.** Agent tabs open in a separate K-Browser window that is never brought to the front. Keyboard and
  mouse input reach the page without taking your keyboard.
- **Real input, re-checked.** Clicks and typing go through Chrome's input pipeline. Right before each press, K-Browser checks
  that the target is still the element the agent meant; if not, it stops instead of clicking something else.
- **Blocked site categories.** At install you choose the categories agents may not use: `banking`, `payments`, `email`,
  `government`, `crypto`, `passwords`. You can block different categories per agent, and change them later in the side panel.
  A tab that lands on a blocked site answers only `blocked_origin`.
- **Page text is data.** Everything taken from a page comes back wrapped in `<untrusted-page-content>`, so the agent can
  tell it apart from instructions. Password fields are never read; tokens, card numbers and the like are masked in network
  logs.
- **Hand-offs.** For a login, a captcha or a decision, the agent hands the tab to you. The extension's popup shows
  **Show** and **Return**; the agent waits until you return it.
- **Activity panel, revocation.** The side panel lists every agent's tabs and actions. You can revoke an agent's access
  there at any time.
- **Risky tools are off by default.** `eval` stays off until you turn it on for a specific client.

## Requirements

- macOS (the bridge runs as a LaunchAgent)
- Google Chrome 125 or later
- Node.js 22 or later (`node -v`)

## Install

Everything goes through `npx`; nothing needs write access to npm's global folder. Below, `npx k-browser <command>` runs
the K-Browser installed in step 1 (installed [from a git clone](#install-from-a-git-clone) instead? Type
`k-browser <command>`).

### 1. Install, register with your agents and start the bridge

Run this in a **real terminal**, not through an agent (npx asks once whether to download K-Browser):

```sh
npx k-browser@latest install
```

It does four things:
- Puts K-Browser in `~/.k-browser/app`. Agents, the bridge and Chrome all use that copy, so clearing npm's cache does
  not break anything.
- Asks which site categories to block for agents (comma-separated; press Enter for none).
- Creates a client with its own token for each agent and writes it into that agent's MCP configuration. A backup of every
  file it changes is kept; `k-browser restore <backup.json>` puts one back.
- Installs the bridge as a LaunchAgent, so it starts when you log in.

Without a terminal to ask in (for example from inside an agent), give the answer on the command line, or install refuses:

```sh
npx k-browser@latest install --block banking,email     # block these categories
npx k-browser@latest install --block ""                # block nothing
```

Add `--dry-run` to see which files would change. `--client claude-code|codex|antigravity|gemini-cli` installs for one agent only.

### 2. Load the extension into Chrome

1. Open `chrome://extensions`.
2. Turn on **Developer mode** (top right).
3. Click **Load unpacked** and choose the folder `npx k-browser extension-path` prints
   (`~/.k-browser/app/node_modules/k-browser/extension`). In the file dialog, Cmd+Shift+G opens a path; Cmd+Shift+. shows
   hidden folders such as `.k-browser`.

A red **K** appears in the toolbar. Pin it: you will use it when an agent hands a tab to you.

### 3. Pair the extension with the bridge

The pairing code is a shared secret between the bridge and the extension. Without it the bridge accepts no extension, and
no other program can pretend to be one.

```sh
npx k-browser pair
```

Paste the code into the K-Browser popup and click **Pair**. The status turns green (**Connected**).

- Wrong code: the status turns red and the field comes back; paste the right one.
- New code (for example if you think it leaked): `npx k-browser pair --rotate`. The old one stops working at once, in every
  Chrome profile: paste the new one in each.
- "Bridge not connected" is not a pairing problem: the bridge is not running. See `k-browser doctor`.

**Several Chrome profiles.** Load the extension in each Chrome profile you want agents to use (work, personal...) and
paste the **same** code in each. From the second profile on, also give it a name in the popup. Agents then pick one with
`tabs {action: "open", profile: "work"}` (default: the profile paired first, or `k-browser profile default <name>`);
`status` and `tabs list` say which profile each tab is in. Every agent can use every paired profile. Manage them with
`k-browser profile list | rename | remove | default`. A removed profile stays out until you pair it again from its popup.

### 4. Check

```sh
npx k-browser doctor
```

`"ok": true` with `startedBy: "launchd"` means everything is ready. Restart your agent (or reconnect its `k-browser` MCP
server) and it has the K-Browser tools.

### 5. Update

```sh
npx k-browser update
```

It installs the newest release into `~/.k-browser/app` (only when there is a newer one) and restarts the bridge; agents
follow by themselves. Then click ↻ for K-Browser at `chrome://extensions`, in each Chrome profile. Do not remove the
extension: removing it forgets its pairing.

### Install from a git clone

For working on K-Browser itself, or if you installed it this way before:

```sh
git clone https://github.com/kaiwutech-TW/k-browser.git K-Browser
cd K-Browser
npm install
npm link       # adds the k-browser command; if it fails, use `node src/cli.js` instead
k-browser install
```

Load the clone's `extension/` folder in Chrome, and update with `k-browser update` (git pull, `npm ci`, restart the
bridge). A clone and the npx install cannot both be installed: `npx k-browser install` stops and says so.

**Switching from a git clone to npx.** In the clone, run `k-browser uninstall`. Then run `npx k-browser@latest install`.
In each Chrome profile, **Remove** the old K-Browser at `chrome://extensions`, **Load unpacked** the folder
`npx k-browser extension-path` prints, and paste the code from `npx k-browser pair` (the same code: do not rotate it).
The reloaded extension counts as a new Chrome profile; to give it its old name, run `npx k-browser profile remove <old name>` first.

## Tools agents get

| Tool | What it does |
|---|---|
| `tabs` | List, open or close the agent's own tabs (opened in the background). |
| `navigate` | Load a URL in a tab, or reload it. |
| `snapshot` | The page's accessibility tree, with refs for interactive elements. |
| `read` | Visible text of the page or one element, or rows matched by a CSS selector. |
| `act` | Click, type, press keys, select, scroll: real input, re-checked before each step. |
| `wait_for` | Decide whether an action worked: the screen changed, the site replied, or the business result is confirmed. |
| `network` | Requests seen in a tab, with response bodies on request; secrets masked, no headers. |
| `fetch` | GET or HEAD on the tab's own origin with the tab's cookies. |
| `files` | The agent's own file area: download into it, upload from it into a file input. |
| `webmcp` | Tools a site offers itself (WebMCP, `document.modelContext`): list and call them. A tool the site marks consequential (a payment, a submission) first needs your **Allow** in the K-Browser side panel. Needs WebMCP turned on in Chrome. |
| `screenshot` | PNG of the visible page or one element; never stored. Can be turned off per client. |
| `needs_human` | Hand a tab to you (login, captcha, decision). The agent waits in the same turn and goes on as soon as you press **Return** (交還) in the K-Browser popup; no need to come back to the chat. If the agent stopped meanwhile (you interrupted it), tell it you are done. |
| `learnings` | Site notes kept on this machine (APIs, walls, pitfalls, tips). Notes are information, never instructions. |
| `status` | Versions, the agent's tabs and hand-offs, which tools are on. |
| `eval` | Run a JavaScript expression in an isolated world. **Off by default.** |
| `run_flow` | Run a saved [Kav](#optional-kav-flows) flow. Only appears when Kav is set up. |

## Everyday commands

Installed with npx, type `npx k-browser` where the table says `k-browser`.

| To | Run |
|---|---|
| Check that everything works | `k-browser doctor` |
| Update K-Browser | `k-browser update` (npx install: the newest release; a git clone: git pull and `npm ci`; both restart the bridge), then click ↻ for K-Browser in `chrome://extensions` in each Chrome profile (do not remove it) |
| Restart the bridge | `k-browser service restart` |
| List / add / remove clients | `k-browser client list`, `client add <name>`, `client remove <name>` |
| Let a client use `eval` | `k-browser client set <name> --eval on` (from its next call) |
| Manage the paired Chrome profiles | `k-browser profile list`, `rename <old> <new>`, `remove <name>`, `default <name>` |
| Give a CDP program its endpoint | `k-browser endpoint <name>` (the URL contains a token; keep it private) |
| Manage site notes | `k-browser learnings list / add / remove / export / import` |
| Remove everything K-Browser registered | `k-browser uninstall` (removes only K-Browser's own entries and tokens) |

**Side panel.** Click the K-Browser icon and open the activity panel. It shows each agent's tabs and actions. From there you
can also revoke an agent, change its blocked categories, turn its screenshots on or off, and turn `eval` off.

**Activity log on disk.** Set `"activityLog": "disk"` in `~/.k-browser/config.json`. Logs go to `~/.k-browser/activity/`
and are kept for 7 days.

## Optional: Kav flows

[Kav-FastwebAgent](https://github.com/kaiwutech-TW/kav-fastwebagent) runs saved, hand-written website flows quickly,
without a model call per step. With Kav set up, agents get a `run_flow` tool that runs a flow in your Chrome as that
agent, under the same ownership and blocking rules. K-Browser works fully without Kav.

```sh
k-browser kav <path to your Kav checkout>     # needs Kav 0.0.8 or later, with uv sync done there
k-browser kav off                             # stop offering run_flow
```

Kav can also connect to K-Browser on its own: `k-browser client add kav`, then set `KFW_CDP` to the URL that
`k-browser endpoint kav` prints. The endpoint supports the subset of the Chrome DevTools Protocol that Kav uses, with
K-Browser's rules applied; other CDP libraries may hit methods it refuses.

**Where Kav's judgement calls go.** Some flow steps need a judgement ("which row is the one the user wants?"). Kav asks the
bridge, which forwards the question as you chose:

| `k-browser model …` | Where the question goes |
|---|---|
| `kev` (default) | A local Kev model on this machine. |
| `jev` | TypeSafe's cloud JEV model. Before turning it on, K-Browser shows what will be sent and asks you to agree; the key is kept in `~/.k-browser/jev.key`, never in an agent's configuration. Passwords, tokens, card and phone numbers are masked first (rule-based; it cannot catch every piece of personal data). Clients with blocked sites cannot use JEV. |
| `off` | Nowhere: Kav hands the choice back to the agent with the candidates. |

The side panel can switch this too. Switching back to `kev` or `off` stops cloud requests from the next question on.

**Decision dataset (off by default).** With `"decisionLog": "on"` in `~/.k-browser/config.json` (or the switch in the side
panel), each judgement Kav makes during `run_flow` is kept, redacted, in `~/.k-browser/decisions/` for 30 days, so model
choices can be compared later. `k-browser decisions purge` deletes it all.

## Where things are kept

Everything lives in `~/.k-browser/` (override with `KBROWSER_HOME`), readable only by you:

| Path | What |
|---|---|
| `pair.key` | The pairing code |
| `clients/<name>.json` | Each client's token and settings |
| `config.json` | Settings (`activityLog`, `decisionLog`, `kav`, model choice) |
| `files/` | Each client's own file area |
| `activity/`, `decisions/` | Logs, only when turned on |
| `jev.key` | The JEV key, only if you chose `jev` |

Do not sync this folder to the cloud or share it.

## Troubleshooting

- **After a bridge restart the agent cannot find its earlier tabs.** On purpose: rather than guess which tabs were whose,
  K-Browser lets them go. Close them by hand.
- **The agent reports `bridge_version`.** The bridge and the agent's MCP server run different versions. If the bridge is
  older, run `k-browser service restart`; if the agent is, restart it or reconnect its MCP server. From 0.5.0 on, an
  agent's MCP server follows updates by itself (after `k-browser service restart`); one started before 0.5.0 needs
  reconnecting once.
- **`chrome://extensions` still shows an old version.** Chrome runs the extension from the folder you chose with **Load
  unpacked**, and does not reload it when the files change. After `k-browser update` (or `git pull`), click ↻ for
  K-Browser at `chrome://extensions`, in each Chrome profile. If it still shows the old version, look at the path on the
  K-Browser card (Developer mode on): it must be the folder `k-browser extension-path` prints. If it is another copy (an
  older clone, or npx's cache), click **Remove**, **Load unpacked** the right folder and pair it again.
- **Chrome shows "… started debugging this browser".** That is Chrome's fixed notice when an extension uses the debugger
  API. Pages cannot see it.
- **Something else.** `k-browser doctor` reports the bridge, the pairing and the extension, and what to do next.

## Limitations

- macOS only for now.
- Every agent can use every paired Chrome profile; limiting an agent to some profiles is not there yet.
- The CDP endpoint is a deliberately limited subset (see above), not a general remote-debugging port.
- Masking is rule-based. Blocking categories and the `untrusted-page-content` wrapper reduce risk; they do not make it
  safe to point an agent at sites you would not trust it with.

## Development

```sh
npm test              # unit tests
npm run typecheck     # tsc --checkJs over src/, extension/ and test/
npm run test:chrome   # end-to-end in Chrome for Testing with the real extension
npm run test:pack     # npm pack, install the tarball elsewhere and through npx, run what got installed
```

- `test:chrome` needs Chrome for Testing (branded Chrome no longer loads unpacked extensions from the command line):
  set `KBROWSER_TEST_CHROME` to its binary, or run `npx playwright install chromium` and the newest one in Playwright's
  cache is used (Apple silicon). Without it these tests are skipped. Set `KBROWSER_TEST_HEADED=1` to watch.
- Tests never use your `~/.k-browser` or the bridge on port 9444; each one starts its own.
- Tests against a real Kav run when `KBROWSER_TEST_KAV` points at a Kav checkout (or one sits next to this repo), and are
  skipped otherwise.
- `package.json` and `extension/manifest.json` carry the same version; a test checks it. Bump both when the bridge or the
  extension changes, so `doctor` can tell old code from new.

## Acknowledgements

K-Browser was designed after reviewing [BeatBrowser](https://github.com/BeatAPI/BeatBrowser) (MIT). No code was taken from it.

## License

[MIT](LICENSE)