pi-kimi-webbridge-bootstrap

English | 简体中文

Use Kimi WebBridge inside Pi to control your real browser — with your existing login sessions — without installing Kimi Code.

This package is a lightweight bootstrapper and updater: it fetches the official Kimi WebBridge CLI, starts the local daemon, and exposes the version-matched WebBridge skill to Pi directly from Moonshot AI's official CDN (https://cdn.kimi.com/webbridge).

• Zero-config setup — automatically installs the platform CLI into ~/.kimi-webbridge/bin/ and starts the local daemon on session start.
• Version-aligned skill discovery — downloads the official skill matching your active daemon version and exposes it to Pi via resources_discover.
• Safe, non-blocking updates — verifies SHA-256 checksums, validates archive safety before atomic activation, and checks for updates in the background every 6 hours.

---

Requirements

• Pi with package and resources_discover support (verified on Pi >= 1.0.2)
• Node.js >= 20
• macOS or Linux (arm64 / x64) (Windows release metadata is recognized, but skill extraction requires a compatible tar binary and is not officially validated.)
• Kimi WebBridge Browser Extension installed in Chrome or Edge

---

Installation

Install from npm:

pi install npm:@specode/pi-kimi-webbridge-bootstrap

Or install from GitHub (avoid pinning a tag/commit if you want pi update --extensions to update this package):

pi install git:github.com/specode/pi-kimi-webbridge-bootstrap

For local development:

pi install /absolute/path/to/pi-kimi-webbridge-bootstrap

---

Quick Start

1. Reload Pi after installing the package (the first load may take a few seconds to download the official CLI and skill):

/reload

2. Install and enable the browser extension:

   • Install Kimi WebBridge from the Chrome Web Store and ensure it is enabled.
   • (If no browser connection is detected on first run, Pi will display this setup link automatically.)

3. Verify the connection:

/webbridge-status

Once Browser extension reports connected, you can ask Pi to open pages, read content, click elements, or automate workflows in your browser.

---

Commands & Configuration

Commands

Command	Description
/webbridge-status	Inspect daemon state, browser extension connection, active skill cache, and last update status
/webbridge-setup	Show browser extension installation steps or confirm that it is already connected
/webbridge-update	Force an immediate release check and refresh the cached Pi skill

Environment Variables

Variable	Default	Description
PI_WEBBRIDGE_AUTO_UPDATE	1	Set to 0 to disable automatic setup and periodic update checks (manual commands still work)
PI_WEBBRIDGE_UPDATE_INTERVAL_HOURS	6	Hours between session-triggered background update checks
PI_CODING_AGENT_DIR	~/.pi/agent	Custom Pi agent directory (skill cache follows Pi's resolved directory)

---

Architecture & Design

Separation of Responsibilities

pi-kimi-webbridge-bootstrap does not vendor Moonshot AI's proprietary runtime or implement its own browser automation. Instead, it manages the lifecycle of the official binary and skill so Pi stays in sync with upstream releases.

Atomic Skill Staging & Rollback

To ensure a broken download or interrupted update never leaves Pi with a half-extracted skill:

1. Verification: New CLI binaries are verified against the SHA-256 checksum in latest/version.json. If a newly installed CLI fails to start or report status, the bootstrapper rolls back to the previous binary.
2. Staged Validation: Skill archives are extracted into an immutable release directory and checked for path traversal, entry types, expanded size limits, and valid SKILL.md frontmatter/version metadata.
3. Atomic Pointer Switch:

   ~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/active.json
   ~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/current -> releases/<version>-<archive-sha256>/
   ~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/releases/<version>-<archive-sha256>/
   

   On macOS/Linux, Pi discovers skills/current, whose symlink target is swapped atomically after validation (active.json serves as the atomic selector on Windows where directory junctions cannot be replaced atomically). Previous validated releases are kept on disk for safe rollback.

Session-Triggered Background Updates & Concurrency

• No OS background bloat: Update checks are triggered by Pi session events (startup, /reload, new session) rather than installing system cron jobs or launch agents.
• Non-blocking startup: Once a cached skill exists, update checks run asynchronously in the background so a slow CDN never blocks Pi startup. When a new skill version is published, the extension prompts you to run /reload (since Pi extensions cannot reliably force a reload during active responses or context compaction).
• Cross-process locking: A process-owned lock at ~/.kimi-webbridge/pi-bootstrap-update.lock prevents concurrent Pi sessions from colliding when updating the shared runtime, automatically reclaiming stale locks if an owner process exits.
• Global daemon note: Because ~/.kimi-webbridge and its daemon are user-global, running kimi-webbridge upgrade briefly restarts the daemon and may also refresh WebBridge skills installed for other agent runtimes.

---

Development

npm test
npm run check

License

MIT