Kimi Webbridge

Kimi Browser Extension (formerly Kimi WebBridge)

Control the user's real browser (with their login sessions) via a local daemon at http://127.0.0.1:10086 (the default address — see If a tool call fails for when it differs).

When the user asks to build a reusable CLI tool or script for a website (rather than do a one-off task), follow references/cli-creator/workflow.md. Its phases say when to read each of these:

• references/cli-creator/site-exploration.md — the protocol for finding how each feature gets its data
• references/cli-creator/login-handling.md — when the site requires login
• references/cli-creator/go-layout.md — when the CLI is written in Go
• references/cli-creator/companion-skill-template.md — the template for the skill that tells agents how to use the CLI

Tools

Tabs and the current tab

Single-tab tools (snapshot, click, fill, screenshot, save_as_pdf) act on the current tab — the one you most recently opened with navigate or selected with find_tab.

• Opening pages: use newTab:true when pages should coexist (comparing, cross-referencing); omit it to send the current tab to a new URL.
• Going back to an earlier tab: call find_tab to make a tab you opened earlier in this session the current one again. Pass the tab's URL — take it from list_tabs or the earlier navigate result. Matching is by host: kimi.com also finds a www.kimi.com tab, and the path is ignored. By default find_tab searches only this session's own tabs — it never reaches into the user's other tabs or windows.
• Acting on a page the user already has open: pass active:true ("use my open X tab" / "the X page I'm viewing"). It borrows the tab the user is currently viewing (returns borrowed:true); the borrowed tab is operated in place — it is not pulled into the session's tab group.
• If find_tab errors with "no tab matching … in this session", the page isn't open in this session — navigate with newTab:true instead.

curl -s -X POST http://127.0.0.1:10086/command \
  -d '{"action":"find_tab","args":{"url":"https://www.kimi.com","active":true},"session":"k26-research"}'

Call Format

Every command carries a top-level session naming the current task — see Sessions below. The examples in later sections omit it only for brevity; in real calls always include it. Every reply is an envelope: {"ok":true,"data":…} on success (the Returns column above describes data) or {"ok":false,"error":{"code","message"}} on failure. The command format depends on the user's OS.

macOS / Linux — inline JSON is fine:

curl -s -X POST http://127.0.0.1:10086/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"navigate","args":{"url":"https://example.com","newTab":true,"group_title":"My task"},"session":"my-task"}'

If the inline call fails — a shell quoting/syntax error from bash, or an HTTP 400 from the daemon — do not retry the same command unchanged. Resend the request as a file body:

1. Write the JSON body to a uniquely-named temp file with your own file-write tool — never with shell echo/heredoc, which mangles the JSON the same way. Use a fresh name per request (e.g. /tmp/webbridge-req-<random>.json).
2. POST the file:

curl -s -X POST http://127.0.0.1:10086/command -H 'Content-Type: application/json' --data-binary @/tmp/webbridge-req-<random>.json

3. Delete the temp file as soon as the request returns.

Windows (PowerShell / cmd) — the shell corrupts non-ASCII characters (Chinese etc.) carried inline in command arguments or pipes; they reach the daemon as ? and the text is unrecoverable. Send every request as a file body instead:

1. Write the JSON body to a uniquely-named temp file with your own file-write tool — never with shell echo/heredoc, which corrupts non-ASCII the same way. Give every request its own filename with a random suffix (e.g. webbridge-req-<random>.json) so concurrent requests never share a file and overwrite each other.
2. POST the file with curl.exe — always curl.exe, never bare curl, which Windows PowerShell aliases to Invoke-WebRequest:

curl.exe -s -X POST http://127.0.0.1:10086/command -H "Content-Type: application/json" --data-binary "@$env:TEMP\webbridge-req-<random>.json"

3. Delete the temp file as soon as the request returns — don't leave request bodies on disk.

Sessions

One task = one session = one tab group. A session collects every tab the task opens into one tab group, so the user sees a single group for "what the agent is doing right now". Pass it as a top-level field of the request body (not inside args).

• Pick one session name at the task's start, put it on every command, and never switch mid-task — even across different sites. Switching session names per site is the #1 cause of fragmented tab groups.
• Name it after the task, not the site (camping-research, phone-compare). Use multiple sessions only for genuinely unrelated parallel tasks.
• group_title is the human-readable group label — write it in the user's language, on the first navigate of the task.
• When you create the group (the first navigate of a task), tell the user once that this task's pages are collected under group «title», and that you'll close them whenever they ask.

# First tab: set session + a human label (in the user's language)
curl -s -X POST http://127.0.0.1:10086/command \
  -d '{"action":"navigate","args":{"url":"https://www.kimi.com","newTab":true,"group_title":"K2.6 feature research"},"session":"k26-research"}'
# Another site, same task → same session → joins the same group automatically
curl -s -X POST http://127.0.0.1:10086/command \
  -d '{"action":"navigate","args":{"url":"https://www.moonshot.cn","newTab":true},"session":"k26-research"}'

Closing is always user-initiated: call close_session only when the user explicitly asks ("close those", "clear the tabs"). It clears the whole group in one call.

Screenshots

The daemon writes the image to disk and returns {format, path, sizeBytes, mimeType} — never base64, since the model can't read raw image bytes. Take the .path and open it with the Read tool to actually see it.

# Default: PNG of the visible viewport, daemon picks a temp path
curl ... -d '{"action":"screenshot","args":{}}'
# Options (each independent): JPEG quality, element-only via @e/CSS selector, custom output path
curl ... -d '{"action":"screenshot","args":{"format":"jpeg","quality":60}}'
curl ... -d '{"action":"screenshot","args":{"selector":"@e123"}}'

A caller-supplied path is honored verbatim (parent dirs created, existing file overwritten) — use a unique name to avoid clobbering. save_as_pdf follows the same rule.

Prefer snapshot over CSS/JS selectors

snapshot returns interactive elements with @e refs based on semantic role/name. Use them directly with click/fill — they survive CSS class hash changes that break manually-written selectors.

Fall back to evaluate (JS) only when:

• The target has no @e ref in the snapshot
• You need attributes not in the snapshot (e.g., href)
• You need to dispatch complex event sequences, or scroll

Evaluate Tips

• Always use compact JSON.stringify(data) — never add null, 2 formatting. Indentation and newlines can inflate the response several times over, causing truncation during transmission.
• evaluate calls share the page's JS realm — re-declaring the same const/let across two calls throws SyntaxError. Wrap in an IIFE for a fresh scope: (() => { const x = ...; return x; })().