pi-inbox

Allow multiple Pi sessions to talk to each other while still staying coherent, with a small agent-facing surface and policy-driven behavior inside the extension.

Install

Install from npm through Pi:

pi install npm:@nqbao/pi-inbox

Or load it locally during development:

pi -e ./index.ts

Package

This is a Pi package and exposes its extension through package.json:

{
  "pi": {
    "extensions": ["./index.ts"]
  }
}

pi-inbox is designed around a simple rule: keep protocol complexity inside Pi, and keep the agent interface as small as possible. The extension focuses on policy between Pi sessions so they can talk to each other without creating too much confusion for the agent, while the agent itself ideally only needs to understand:

• a message was delivered
• reply with inbox_post(channel, message) if a reply is needed

Current Shape

• Pure file-system transport
• Channel-oriented messaging
• Auto-polling and notification injection
• One agent-facing tool: inbox_post
• User-facing commands for subscribe, unsubscribe, post, clear, and status

Current implementation files:

• index.ts
• tools.ts
• transport.ts
• channels.ts
• config.ts

Product Position

pi-inbox is a messaging primitive, not an orchestration runtime.

It is meant to let independent Pi sessions talk to each other while keeping the model loop simple. Coordination complexity such as delivery behavior, claiming, retries, batching, or response shaping should live inside the extension rather than in additional agent tools.

This means pi-inbox focuses on policy among agents:

• who should receive a message
• whether a reply is expected
• whether a message is informational or claimable
• how broadly a message should be delivered
• whether responses should be constrained
• whether urgent items should be broken out from normal batches

The goal is operational sophistication with cognitive simplicity.

Design Principles

• Hide protocol, expose intent
• Keep the agent-facing communication API minimal
• Push messages to the agent instead of making the agent poll
• Keep discovery primarily user-facing
• Use one transport model for both broadcast and peer-to-peer messaging
• Prefer delivery policy over extra coordination tools

Communication Model

Channels are the core primitive.

Examples:

• shared channel: code-review
• shared channel: orchestrator
• peer-specific channel: _dm.worker-abc

Both broadcast-style and peer-to-peer communication should fit within the same channel model.

Current channel names may only contain lowercase letters, ., _, and -.

Policy Direction

The longer-term direction is to let Pi manage communication policy internally while preserving the same small external interface.

Examples of policy dimensions:

• audience: broadcast, selective, direct
• reply expectation: read-only, reply-allowed, single-claimer
• constraints: free-form, yes/no, fixed choices, short structured reply
• priority: high, normal, low

These policies are intended to shape delivery and notification behavior without growing the tool surface.

Current Tool

inbox_post(channel, message)

Posts a message to a subscribed channel.

Current behavior:

• rejects unsubscribed channels
• writes to the channel log
• advances cursor to avoid self-notification

See tools.ts.

Commands

Current user-facing commands:

• /inbox-subscribe <channel>
• /inbox-unsubscribe <channel>
• /inbox-status
• /inbox-post <channel> <message>
• /inbox-clear <channel>

Commands are for user control and inspection. Discovery and richer session awareness should be added here before becoming agent-visible capabilities.

Transport

pi-inbox uses append-only messages.jsonl files under a local inbox directory.

Default shape:

~/.pi/inbox/
  default/
    channels/
      code-review/
        messages.jsonl

This keeps the system:

• local
• durable
• inspectable
• offline-tolerant
• free of broker/daemon requirements

Roadmap

Planned work is documented in PLAN.md.

The main roadmap direction is not “more tools.” It is richer internal policy with a stable, simple agent-facing model.