Plugin development

# Customize PI WEB with UI plugins.

Plugins are trusted browser-side ES modules. They can add actions, workspace panels, and compact workspace labels to the PI WEB UI.

## What can be extended

Plugins can add small, focused UI extensions to PI WEB:

- Action palette commands for custom workflows.
- Workspace tools and panels next to Files, Git, and Terminal.
- Workspace labels in the workspace list, header, and status bar.
- Static assets served from the plugin folder.
- Browser-side integrations using documented PI WEB plugin context helpers.

Plugins cannot extend the session daemon or add server-side hooks. They run in the browser UI only. PI WEB's internal API routes are not plugin API; use documented context helpers instead.

The plugin API is intentionally limited and actively developed. Feedback is appreciated: if an extension point is missing, unclear, or awkward, please open a GitHub issue.

## What to ask AI to build

You do not need to hand-code plugins. Give an AI agent a clear goal, the workspace/project facts it should use, and the PI WEB plugin rules.

- Show a workspace badge from a repo file, environment file, branch name, container, or dev URL.
- Add a workspace panel that summarizes project-specific health, commands, links, or runbooks.
- Add action-palette commands for common project workflows or prompts.
- Add links to local services, preview deployments, dashboards, CI, logs, or docs.

Prompt: create a plugin

    Build a PI WEB plugin for this project.
    Goal: <describe the UI behavior>.
    Before coding, read the PI WEB plugin docs:
    https://pi-web.dev/plugins.html
    Full API reference:
    https://pi-web.dev/plugins.md
    Create it as a local plugin under ~/.pi-web/plugins/<plugin-id>.
    Use the appropriate extension points from the docs.
    Validate by checking /pi-web-plugins/manifest.json and explain how to reload/debug it.
    Do not modify PI WEB itself.

Prompt: improve a plugin

    Improve the PI WEB plugin at <path>.
    Before coding, read the PI WEB plugin docs:
    https://pi-web.dev/plugins.html
    Full API reference:
    https://pi-web.dev/plugins.md
    Keep the plugin compatible with the documented v1 API.
    After editing, check the manifest endpoint and browser-console failure cases.

## Canonical example

PI WEB ships a real bundled Info plugin. It is intentionally small while still using all core contribution types: one action, one workspace label, and one workspace panel.

Bundled PI WEB plugins are developed as TypeScript in the repository, while their package metadata points at the built JavaScript ES modules that the browser loads. `npm run dev:web` watches and rebuilds bundled plugin TS into `dist/pi-web-plugins/` during development, and `npm run build` emits JS before release packaging.

- `pi-web-plugins/info/package.json` shows the required metadata shape.
- `pi-web-plugins/info/pi-web-plugin.ts` shows the TypeScript source shape.
- `dist/pi-web-plugins/info/pi-web-plugin.js` is the built browser module in a checkout.

Read it on GitHub: pi-web-plugins/info. If you copy it, choose a new plugin id so it does not conflict with the bundled `info` plugin.

The bundled `updates` plugin demonstrates dynamic `visible` and `badge` callbacks for tabs that only appear when the host has status messages or needs extra install visibility.

## Built-in plugins

PI WEB ships core, discoverable plugins in the main `@jmfederico/pi-web` npm package. No separate `pi install` step is required: update PI WEB, reload the browser tab, and the bundled plugins appear in `/pi-web-plugins/manifest.json`.

Built-in plugins can be managed from Settings → Plugins or with the top-level `plugins` config key.

### Updates

Updates adds a conditional Updates workspace tab with PI WEB update, restart, and installed-service guidance. It is built into PI WEB and enabled by default.

- Plugin id: `updates`

Disable Updates

    {
      "plugins": {
        "updates": { "enabled": false }
      }
    }

### Workspace Tasks

Workspace Tasks adds a Tasks workspace tab for running configured shell commands in dedicated PI WEB terminals. It is built into PI WEB and enabled by default.

- Plugin id: `workspace-tasks`
- Config file: `.pi-web/tasks.json`

Disable Workspace Tasks

    {
      "plugins": {
        "workspace-tasks": { "enabled": false }
      }
    }

Example .pi-web/tasks.json

    {
      "version": 1,
      "tasks": [
        {
          "id": "docker.start",
          "title": "Start Docker",
          "group": "Docker",
          "description": "Start the local Docker Compose environment.",
          "command": "./docker/scripts/docker-compose-dev up -d"
        },
        {
          "id": "db.reset",
          "title": "Reset DB",
          "group": "Database",
          "command": "go -C klingit-go run ./cli db reset",
          "confirm": true
        }
      ]
    }

Open a workspace, choose the Tasks tab, and click Run next to a task. Commands run in the workspace root because PI WEB creates the terminal for that workspace.

Review task configs before running them, especially in shared projects. Workspace Tasks runs trusted shell commands from your repositories.

## Manage plugins

Open Settings → Plugins to review discovered bundled, local, dev, and Pi package plugins. PI WEB can disable any discovered plugin before the browser imports it. Core app contributions such as the command palette, base workspace tools, and themes are not managed through this plugin list.

Plugin config shape

    {
      "plugins": {
        "workspace-tasks": {
          "enabled": true,
          "settings": {}
        },
        "info": {
          "enabled": false
        }
      }
    }

Plugins are enabled by default. Set `enabled` to `false` to remove a plugin from `/pi-web-plugins/manifest.json` so it is not imported or activated on the next page load. The optional `settings` object is reserved for plugin-specific settings.

After changing plugin enablement, reload the PI WEB browser tab. Already-loaded plugin JavaScript is not unloaded from the current page.

## Production usage

Local plugins work with the production native-service install. Put each plugin under `~/.pi-web/plugins/<plugin-id>/`, or symlink it there while developing. No PI WEB rebuild or session-daemon restart is required.

If `PI_WEB_DATA_DIR` is set, use `$PI_WEB_DATA_DIR/plugins` instead of `~/.pi-web/plugins`.
Install a local plugin folder

    $ mkdir -p ~/.pi-web/plugins
    $ ln -s /path/to/plugin-folder ~/.pi-web/plugins/plugin-id

## AI-friendly docs

The full plugin reference is available as Markdown for AI agents to read, fetch, and follow: plugins.md.

If you want to understand the API yourself, ask an agent to read that file and explain the relevant extension points for the plugin you want. The Markdown reference also marks which context fields are stable and which PI WEB internals should be avoided unless necessary.

## Develop and debug

- Keep the source folder outside `~/.pi-web/plugins` and symlink it in.
- After edits, reload or hard-reload the browser tab.
- Check discovery with the manifest endpoint.
- Check the browser console if a plugin fails to import or activate.

Check discovered plugins

    $ curl http://127.0.0.1:8504/pi-web-plugins/manifest.json

For all contribution types and package metadata, read the Plugin API reference.

## Trust model

Plugins are not sandboxed. They run as JavaScript in the browser, can call PI WEB APIs available to the current session, and can render arbitrary UI. Install only plugins you trust.

Plugins do not run inside the session daemon and do not provide server-side hooks.