blackbird-pi

Deliver durable Blackbird messages into active Pi sessions.

Packages

Package details

extension

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

npm repo home report

$ pi install npm:blackbird-pi

Package: blackbird-pi
Version: 0.2.1
Published: Sep 2, 2026
Downloads: 205/mo · 19/wk
Author: phall
License: MIT
Types: extension
Size: 30.6 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

blackbird-pi

Pi-native queue-mode delivery for Blackbird. Blackbird remains the always-on durable mailbox; this extension connects the currently active Pi session to it. It does not launch or supervise Pi.

pi install npm:blackbird-pi@0.1.0

Start Pi in the repository that should receive messages. The extension registers the stable agent name Pi, catches up Blackbird's durable event journal, and injects visible messages into the current session. Messages are queued as follow-ups while Pi is busy. Delivery does not mark Blackbird facts read or acknowledged.

Blackbird stores delivery progress under the authenticated pi-extension consumer and advances it only after Pi admits the custom message. The local state under $XDG_STATE_HOME/blackbird/pi-extension keeps only the registration token and host-specific quarantine facts. On first use, the extension imports the retired companion cursor once into the server consumer and retains its quarantine state.

Environment overrides:

BLACKBIRD_API_URL defaults to http://127.0.0.1:8080.
BLACKBIRD_PI_AGENT_NAME defaults to Pi.
BLACKBIRD_PI_DISABLED=1 disables the extension.

Use /blackbird inside Pi to inspect connection state.