pi-dev-widget

A pi extension that runs a lightweight background web server so you can chat with pi from inside a local website.

Install

Activation is opt-in per project — the widget never loads unless a project asks for it.

Enable it for a specific project (recommended):

cd /path/to/project
pi install -l /path/to/dev-widget   # writes ./path/to/project/.pi/settings.json

Or add it directly to that project's .pi/settings.json:

{
  "packages": ["/abs/path/to/dev-widget"]
}

Restart pi (or /reload).

Disable for one project

To opt a single project out of a global install, add the package to that project's .pi/settings.json with autoload: false (overrides the global entry for that repo only).

Testing locally (global)

For throwaway testing across many repos you can install it at user level instead — it loads in every project until removed:

pi install /path/to/dev-widget    # no -l → writes ~/.pi/agent/settings.json
pi remove pi-dev-widget           # undo

Use

1. Open pi in your project. On boot the extension prints pi-dev-widget active with the server address and the exact script tag, e.g. http://127.0.0.1:<PORT>.

   The port is derived deterministically from your project's path, so it's stable per machine+cwd. Trust the tag pi prints — not a hardcoded one.

2. Add that tag to any page served from your machine (any port — astro dev, vite, a static file). A left-side toggle tab appears. Hover over it to peek at status/hints; mouse away to collapse; click the toggle, click inside the panel, or click 📌 to keep it pinned open.

3. Type a message, use the crosshair (⌖) to pick one or more page elements, or use the crop tool (✂) to drag-select cropped screenshots of any part of the page with individual descriptions.

How it works

The agent answers the widget only when it explicitly calls the widget_reply tool — pi's terminal output is never streamed to the page.

Remote pages (CSS/hosted-site injection)

The widget API refuses non-localhost origins by default (a random website can't reach your local pi). To inject the widget into a hosted page — e.g. your own site on https://… for CSS/UI tweaks — opt in explicitly:

PI_WIDGET_ALLOW_REMOTE=1 pi

When active, the boot banner reads pi-dev-widget v<version> +++ REMOTE ALLOWED +++, so the lock being off is visible at a glance.

With this on, the loopback API answers any origin instead of 403ing on CORS requests. Re-enables only this opt-in flag; the default stays secure. In the remote page, use http://127.0.0.1:<PORT>/pi.js as the injected script.