# 🌐 dsh-better-browser ### *Let your Agent use the real browser where you are already signed in.* [![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4D6BFE)](https://github.com/deepseek-ai) [![Version](https://img.shields.io/badge/version-0.3.6-4D6BFE)](package.json) [![Node.js](https://img.shields.io/badge/Node.js-22.19%2B-4D6BFE)](package.json) [![License](https://img.shields.io/badge/license-BSD--3--Clause-4D6BFE)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/titanwings/dsh-better-browser?style=social)](https://github.com/titanwings/dsh-better-browser/stargazers)
🔐  Need an Agent to use signed-in websites without copying cookies or signing in again?
🧭  Need navigation, interaction, screenshots, and network inspection in one workflow?
🧠  Want browser state to stay local instead of filling the model context?
### ✨ 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**
[Why it exists](#why) · [Features](#features) · [Install](#install) · [Quick start](#quick-start) · [Tools](#tools) · [Safety](#safety) **English** · [简体中文](README.md)
![dsh-better-browser: your real browser, Agent-ready](docs/social-preview.png)
--- ## 🎯 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**. | | Headless browser | dsh-better-browser | | --- | --- | --- | | Authentication | Usually sign in again or inject credentials | Reuse the user's current browser state | | Tabs | Maintained by the tool | Real tabs and tab groups | | Browser state | Often enters tool output or context | Remains in the browser and local daemon | | Best for | Isolated tests and scraping | Signed-in workflows and real-page inspection | 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. --- ## ✨ 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. --- ## ⚡ 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](https://www.kimi.com/products/kimi-webbridge) and [help center](https://www.kimi.com/help/kimi-webbridge): ```bash 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](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) - [Microsoft Edge](https://microsoftedge.microsoft.com/addons/detail/kimi-webbridge/bnlffdbcfnanfbknnlaflhlhkocccckg) 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 ```bash 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. --- ## 🚀 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. ```text 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. --- ## 🧰 Thirteen browser tools | Tool | Purpose | | --- | --- | | `webbridge_navigate` | Open a URL and name the task's tab group | | `webbridge_find_tab` | Re-select a task tab or borrow the active tab | | `webbridge_snapshot` | Read the accessibility tree and `@e` element refs | | `webbridge_click` | Click by `@e` ref or CSS selector | | `webbridge_fill` | Fill inputs, textareas, and contenteditable elements | | `webbridge_evaluate` | Run synchronous or asynchronous JavaScript | | `webbridge_screenshot` | Capture a page or element and return its path | | `webbridge_list_tabs` | List tabs in the current session | | `webbridge_network` | Start, stop, and inspect network activity | | `webbridge_upload` | Upload files from the calling Agent workspace | | `webbridge_save_as_pdf` | Save the current page as a PDF | | `webbridge_close_tab` | Close the session's current tab | | `webbridge_close_session` | Close every tab in the session | --- ## 🛡️ 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
Configuration
| Field | Default | Meaning | | --- | --- | --- | | `baseUrl` | `http://127.0.0.1:10086` | Daemon http/https address | | `timeoutMs` | `30000` | Per-tool timeout budget in milliseconds | ```yaml - id: webbridge config: baseUrl: http://127.0.0.1:10086 timeoutMs: 30000 ``` Invalid URLs and non-positive timeouts fail loudly when the plugin mounts.
Upgrade from the old name
Profiles with the old package must remove it before installing the new version: ```bash 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.
Current limitations
- 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.
Development and tests
DSH official packages are not on the public npm registry, so development needs a DSH source checkout: ```bash 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.
--- ## 📄 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.