K-Browser

繁體中文

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

Below, k-browser means node src/cli.js run in this folder. Run npm link once in this folder to have a k-browser command everywhere.

1. Get the code

git clone https://github.com/kaiwutech-TW/k-browser.git K-Browser
cd K-Browser
npm install

2. Register with your agents and start the bridge

Run this in a real terminal, not through an agent:

k-browser install

It does three things:

• 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:

k-browser install --block banking,email     # block these categories
k-browser 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.

3. Load the extension into Chrome

1. Open chrome://extensions.
2. Turn on Developer mode (top right).
3. Click Load unpacked and choose the extension/ folder in this repo (k-browser extension-path prints the full path).

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

4. 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.

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): k-browser pair --rotate. The old one stops working at once.
• "Bridge not connected" is not a pairing problem: the bridge is not running. See k-browser doctor.

5. Check

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.

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.
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) and wait.
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 flow. Only appears when Kav is set up.

Everyday commands

To	Run
Check that everything works	k-browser doctor
Restart the bridge (after updating the code)	k-browser service restart, then click ↻ for K-Browser in chrome://extensions (do not remove it)
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, then restart that agent
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 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.

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.
• 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.
• 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

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, 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 (MIT). No code was taken from it.

License

MIT