# pi-kimi-webbridge-bootstrap

[English](./README.md) | [简体中文](./README.zh-CN.md)

A [Pi](https://github.com/earendil-works/pi-mono) extension that installs and updates the official [Kimi WebBridge](https://www.kimi.com/) CLI, local daemon, and Pi skill so Pi can operate your browser with your existing login sessions.

`/webbridge-status` output:

```text
WebBridge daemon: running (v0.1.3)
Browser extension: connected
Pi skill: v0.1.3
CLI: ~/.kimi-webbridge/bin/kimi-webbridge
Skill: ~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/current/kimi-webbridge
```

## Requirements

- Pi with `resources_discover` support (tested with Pi 1.0.2 and later)
- Node.js >= 20
- macOS or Linux (`arm64` or `x64`)
- [Kimi WebBridge browser extension](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) installed and enabled in Chrome or Edge

## Installation

From npm:

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

From GitHub:

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

From a local directory for development:

```bash
pi install /path/to/pi-kimi-webbridge-bootstrap
```

Run `/reload` or restart Pi after installing.

## Usage

1. On first session start (or `/reload`), the extension downloads the official CLI to `~/.kimi-webbridge/bin/`, starts the local daemon, and caches the matching skill under `~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/`.
2. Install and enable the [Kimi WebBridge browser extension](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) in Chrome or Edge. If no browser connection is detected on first run, Pi shows this link automatically.
3. Run `/webbridge-status` and check that `Browser extension` reports `connected`.
4. Once a cached skill is installed, the extension checks for updates in the background on session start every 6 hours without blocking startup. When a new skill version is downloaded, Pi prompts you to run `/reload`.

### Commands

| Command | Description |
| --- | --- |
| `/webbridge-status` | Show daemon state, browser extension connection, cached skill version, and last update error |
| `/webbridge-setup` | Show browser extension installation steps or confirm that it is connected |
| `/webbridge-update` | Check for a newer release immediately and update the CLI and cached skill |

## Configuration

| Environment 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 (retries after 15 minutes on failure) |
| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Custom Pi agent directory (skill cache follows Pi's resolved directory) |

## Privacy and Safety

- Downloads official binaries and skills only from `https://cdn.kimi.com/webbridge`; no proprietary binaries or skill archives are bundled in this package.
- Verifies CLI binaries against the SHA-256 checksum in `latest/version.json` and rolls back to the previous binary if the new CLI fails to start or report status.
- Validates skill archives in a staging directory (checking tar headers, entry types, path traversal, expanded size limits, and `SKILL.md` frontmatter) before atomically switching `skills/current`.
- Uses a process lock at `~/.kimi-webbridge/pi-bootstrap-update.lock` so concurrent Pi sessions do not collide during updates, reclaiming stale locks only when the owner process has exited.
- Does not register OS-level cron jobs or launch agents; update checks run only on Pi session events. Note that `~/.kimi-webbridge` and its daemon are shared across the user account, so `kimi-webbridge upgrade` briefly restarts the shared daemon.

## Development

```bash
# Run tests
npm test

# Syntax-check and run tests
npm run check

# Check package contents
npm run pack:check
```

## License

[MIT](./LICENSE).