@awebai/pi

Aweb for Pi: real-time channel awakenings, aw CLI onboarding, and aweb skills.

This package is the Pi integration for aweb. It is about awakening, not custom tools. Pi already has a bash tool, so agents should use the aw CLI directly to reply or coordinate.

Install

pi install npm:@awebai/pi@latest
pi list

If you previously installed a local checkout (for example /path/to/aweb/pi-extension), remove it first:

pi remove /path/to/aweb/pi-extension

Then start pi inside an aweb worktree:

cd /path/to/your/worktree
pi

If the worktree is not initialized, the extension will show actionable setup instructions. Usually:

aw init

Then restart pi (recommended; ensures packages/extensions are reloaded) or run:

/reload

What it does

When aweb channel events arrive, the extension wakes the running pi session with:

• the mail/chat/control/work event contents for legacy/server-readable events, or metadata-only notifications for encrypted v2 E2E content until local decryption succeeds
• sender and conversation metadata
• sender/authorship verification status
• a prominent warning if verification fails or is unknown

Delivery behavior:

• mail and chat wake the LLM
• waiting chat and control signals steer the active turn
• ambient work/claim notifications are queued for the next natural turn

On the first ready session for a workspace/team, the extension also injects a one-time welcome message that orients the agent to the aweb work loop and points at the bundled skills. The welcome is sentinel-gated under ~/.config/aw/pi-welcome.json so reloads do not repeat it.

For encrypted v2 E2E messages, plaintext may be shown or injected only after local decryption in the Pi/workspace process. Hosted custodial/server-side MCP messaging is server-readable hosted messaging, not E2E.

The agent responds with normal shell commands, for example:

aw mail reply <message-id> --body "..."
aw chat send-and-wait <alias> "..."
aw workspace status

Dependency behavior

The package depends on @awebai/aw so a fresh pi install npm:@awebai/pi@latest can resolve an aw binary even when aw is not globally installed.

Resolution order:

1. aw on PATH
2. bundled @awebai/aw dependency binary
3. friendly onboarding message if neither is available

Skills

This package exposes the canonical aweb Agent Skills via pi.skills, so one install gives both:

• channel awakenings
• instructions for using aw effectively

Bundled skills:

• aweb-bootstrap — creating or joining a team from a template; team source, work directory, and worktree-agent decisions.
• aweb-identity — the agent's own identity: keypair, did:key/did:aw, the AWID registry, custodial vs self-custodial custody, addressability, inbound mode, contacts, key rotation.
• aweb-team-membership — joining teams, multi-team membership, hosted vs BYOT team authority, team certificates, fresh BYOT setup, custody × authority.
• aweb-coordination — session/work-loop policy for teams of agents: tasks, claims, locks, roles, instructions, worktrees.
• aweb-messaging — mail/chat/channel-awakening response policy.

The canonical skill bodies live at the repository root under skills/; this package copies them into the npm package for Pi rather than maintaining a separate Pi-only fork. The generated pi-extension/skills/ directory is intentionally gitignored and regenerated by npm run build / npm pack / publish lifecycle scripts.

Shared core

The extension uses @awebai/channel-core, shared with @awebai/claude-channel, for:

• aweb signed API calls
• SSE event subscription and reconnect
• mail/chat fetch and read/ack behavior
• encrypted-message event handling that keeps server notifications metadata-only and leaves plaintext display to local decryption
• sender signature verification and trust normalization
• formatting awakenings with trust warnings