pi-peer-messages

Let pi agent sessions message each other peer-to-peer over iroh.

Packages

Package details

extension

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

npm repohome report
$ pi install npm:pi-peer-messages
Package
pi-peer-messages
Version
0.1.1
Published
Oct 24, 2026
Downloads
494/mo · 494/wk
Author
fdietze
License
MIT
Types
extension
Size
39.4 KB
Dependencies
1 dependency · 3 peers
Pi manifest JSON
{
  "extensions": [
    "extensions/peer-messages/index.ts"
  ]
}

Security note

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

README

pi-peer-messages

Let Pi agent sessions message each other peer-to-peer, across Pi processes and machines, over iroh.

Every Pi session has one stable peer address. Whoever knows it may message that session, and the session may reply. Share your address to grant that permission.

Install

Requires Pi 1.2.0 or newer.

pi install npm:pi-peer-messages

Usage

  1. In the receiving session, run /peer-address and copy the address.
  2. Give it to the other agent, e.g. "send your findings to peer <address>".
  3. The other agent calls send_peer_message. The message arrives as [peer message from <sender address>] and starts or steers a turn; the receiver can reply to that address.
Interface Purpose
send_peer_message({ address, text }) Send a message. Result: delivered (accepted by the receiving session), not delivered, or unknown (may have arrived; a retry can duplicate it).
/peer-address Make this session reachable and show its address.

A session listens only after /peer-address or its first send_peer_message, and again after every resume. Forks and new sessions get new addresses. Subagents of pi-actor-subagents get their own addresses if this extension is listed in its childExtensions.

Limits

  • Best-effort: an offline receiver gets nothing; there is no mailbox.
  • Messages up to 64 KiB; 10 s per delivery.
  • Addresses are visible to iroh's public discovery and relay servers (n0) and to your model provider via transcripts. A shared address cannot be revoked except by starting a new session.
  • Two agents replying to each other can loop; every reply is a model turn.

The secret is ~/.pi/agent/pi-peer-messages/master.key; session keys are derived from it. See DESIGN.md for the protocol and rationale.