<div align="center">

🌐 dsh-better-browser

Let your Agent use the real browser where you are already signed in.

    

<br>

<table> <tr><td align="left">

🔐 &nbsp;Need an Agent to use signed-in websites without copying cookies or signing in again?<br> 🧭 &nbsp;Need navigation, interaction, screenshots, and network inspection in one workflow?<br> 🧠 &nbsp;Want browser state to stay local instead of filling the model context?

</td></tr> </table>

✨ dsh-better-browser turns your real browser into thirteen Agent tools.

Reuse logins, open tabs, and live sessions through the local Kimi WebBridge. DSH owns the model tools; browser state remains in the browser.

Real browser + local bridge + 13 tools → complete Agent-driven browser workflows

<br>

[Why it exists](#why) · [Features](#features) · [Install](#install) · [Quick start](#quick-start) · [Tools](#tools) · [Safety](#safety)

English · 简体中文

<br>


</div>

---

<a id="why"></a>

🎯 Why dsh-better-browser

Headless browsers are useful for isolated tests, but they do not naturally reuse the logins, cookies, tabs, and site sessions you already have open. dsh-better-browser connects to the local Kimi WebBridge daemon so a DSH Agent can operate the user's own browser.

This plugin contains no browser-driving code. Kimi WebBridge's daemon and browser extension perform the browser actions; the plugin adapts their local protocol into DSH model tools.

---

<a id="features"></a>

✨ Features

🌍 Operate the user's real browser

Navigate, read accessibility snapshots, click, fill, and evaluate JavaScript while preserving signed-in state and already-open tabs.

🔎 Capture evidence beyond page text

The Agent can take screenshots, inspect network activity, upload files, and save PDFs without placing the complete browser state in the model request.

🗂️ One task, one tab group

A stable session name groups the tabs for one task. Separate tasks do not mix, and the user can watch or take over the workflow in their own browser.

🔌 No DSH Core patch

The Cordis bundle registers the stable webbridge row and thirteen webbridge_* tools. Removing the bundle removes the capability.

---

<a id="install"></a>

⚡ Install

1. Install Kimi WebBridge

Kimi WebBridge is an independent Moonshot AI product. This repository does not contain its daemon or browser extension. Follow Kimi's official product page and help center:

curl -fsSL https://cdn.kimi.com/webbridge/install.sh | bash
kimi-webbridge status   # expect "extension_connected": true

Install the Kimi WebBridge extension from an official store:

• Google Chrome
• Microsoft Edge

Keep that browser running after enabling the extension, then run kimi-webbridge status again. The complete browser–daemon–plugin path is ready only when it reports "extension_connected": true.

2. Install the DSH plugin

dsh plugin --profile web add github:titanwings/dsh-better-browser#v0.3.6

Restart dsh web and refresh the page. The model can then see the webbridge_* tools. If the daemon is unavailable, tools return daemon_unreachable instead of silently degrading.

---

<a id="quick-start"></a>

🚀 Quick start

After installation, ask the Agent:

> Use my real browser to open GitHub, find this repository's Issues, and inspect > the latest three. Do not close my existing tabs.

The Agent chooses a stable session, navigates, reads the page, and performs each interaction in order. Browser actions use exclusive scheduling and never mutate shared tabs concurrently.

navigate → snapshot → click/fill → snapshot → screenshot/network

Tabs close only when the user explicitly requests it; task completion never cleans up the user's browser automatically.

---

<a id="tools"></a>

🧰 Thirteen browser tools

---

<a id="safety"></a>

🛡️ Session and safety boundaries

• One task = one session = one tab group. Keep the same session name on

every call.

• Closing is user-initiated. Close a tab or session only after an explicit

user request.

• Browser actions are serialized. Every tool declares

isConcurrencySafe=false to prevent interleaved mutations of shared tabs.

• Host paths stay scoped. Uploads must be existing regular files inside the

calling Agent workspace after canonical-path resolution (symlink escapes are rejected). Screenshot and PDF paths are accepted only from WebBridge's dedicated temporary directories.

• Navigation stays on web origins. navigate and find_tab accept only

absolute http/https URLs; local-file and script schemes are rejected.

• Local-first does not mean risk-free. The Agent operates a real signed-in

session; sending, submitting, or publishing must still follow DSH confirmation and permission policies.

• The Agent sees the evidence needed for the next step. Accessibility

snapshots, tabs, network detail, and screenshot/PDF paths accompany the summary; model-visible output is capped at 32,000 characters with explicit truncation.

---

🔧 Technical details

<details> <summary><strong>Configuration</strong></summary>

<br>

- id: webbridge
  config:
    baseUrl: http://127.0.0.1:10086
    timeoutMs: 30000

Invalid URLs and non-positive timeouts fail loudly when the plugin mounts.

</details>

<details> <summary><strong>Upgrade from the old name</strong></summary>

<br>

Profiles with the old package must remove it before installing the new version:

dsh plugin --profile web remove @dsh-external/dsh-kimi-browser
dsh plugin --profile web add github:titanwings/dsh-better-browser#v0.3.6

The @dsh-external/dsh-better-browser package identity, webbridge row id, tool names, and config fields remain stable. Moving the GitHub repository does not change the Cordis bundle identity.

</details>

<details> <summary><strong>Current limitations</strong></summary>

<br>

• Sites that strictly check event.isTrusted may reject synthetic click/fill.
• Snapshot, click, fill, and evaluate operate on the top frame only and do not

cross into cross-origin iframes.

• Screenshot returns a temporary path written by the daemon; use a Read tool to

inspect it.

• The daemon owns tab groups, so restarting it clears them.

</details>

<details> <summary><strong>Development and tests</strong></summary>

<br>

DSH official packages are not on the public npm registry, so development needs a DSH source checkout:

pnpm link:dsh -- /path/to/dsh
pnpm typecheck
pnpm test
pnpm build
pnpm check

Tests cover the daemon client, thirteen tools, Cordis lifecycle, configuration, and Loader smoke path. Set KIMI_WEBBRIDGE_IT=1 to run against a live daemon.

</details>

---

📄 License and WebBridge boundary

This plugin uses BSD-3-Clause; see [LICENSE](LICENSE). It implements a compatible Kimi WebBridge protocol adapter and contains none of Kimi's daemon, extension, or code. Kimi WebBridge is a Moonshot AI product and trademark and must be installed and used under Kimi's own terms.