pi-widget-host

Host package for managing one shared Pi widget slot across multiple providers with preset policies and a built-in demo provider.

Packages

Package details

extension

Install pi-widget-host from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-widget-host
Package
pi-widget-host
Version
0.2.0
Published
Jun 15, 2026
Downloads
not available
Author
eiei114
License
MIT
Types
extension
Size
35.1 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extensions/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Pi Widget Host

CI Publish npm version npm downloads License: MIT Pi package Trusted Publishing

Shared-slot host for managing one prompt-top Pi widget across multiple providers.

What this is

pi-widget-host owns one shared widget slot in Pi and picks a single winner from registered providers.

v1 is a Host-only MVP:

  • user-global config under ~/.pi/agent/
  • preset-first time-block policy
  • globalThis registry protocol for future provider packages
  • built-in demo provider for setup and dogfooding
  • silent empty slot when nothing should render

Features

  • /widget-host:setup guided first-run flow
  • /widget-host:status, /widget-host:policy, /widget-host:providers
  • /widget-host:mute and /widget-host:unmute
  • event boost for playing-now and matchday
  • known host tags: music, sports, playing-now, matchday, idle

Install

Published package:

pi install npm:pi-widget-host

GitHub install:

pi install git:github.com/eiei114/pi-widget-host

Local dev:

pi -e .

Quick start

Run the host locally, then open these commands:

/widget-host:setup
/widget-host:status
/widget-host:providers

/widget-host:setup asks whether to enable the built-in demo provider and which preset policy to save.

Commands

  • /widget-host:setup — save initial preset and optionally enable the demo provider
  • /widget-host:status — report setup status, preset, and active provider
  • /widget-host:policy — show or change the saved preset
  • /widget-host:providers — inspect known provider entries and effective state
  • /widget-host:mute — mute one provider in host config
  • /widget-host:unmute — unmute one provider in host config

Commands take no inline arguments. Input is collected with Pi UI prompts.

Registry protocol

Future provider packages can publish to the host without importing this package at runtime.

  • backing: globalThis
  • symbol: Symbol.for("pi-widget-host.registry.v1")
  • required fields: providerId, available, lines, updatedAt
  • optional fields: priority, tags, mode, ttlMs

See docs/protocol.md.

Built-in demo provider

The built-in demo provider exists to prove the host loop first:

  • setup enables it explicitly
  • it publishes through the same registry protocol as future packages
  • it renders provider-owned lines through the shared host slot
  • if muted, disabled, or filtered out by policy, the slot disappears

Package contents

Path Purpose
extensions/ Pi extension entrypoint and command registration
lib/ config store, registry protocol, policy evaluation, demo provider
docs/ supporting docs such as release and protocol notes

Development

npm install
npm run ci

Release

This package uses npm Trusted Publishing.

npm version patch
git push

See docs/release.md.

Security

Pi packages execute with your local permissions. Review extensions before installing third-party packages.

For vulnerability reporting, see SECURITY.md.

Links

License

MIT