Nostr for pi and pi-durable: direct messages (NIP-17), rooms (NIP-29), and public notes and comments (kinds 1 and 1111), built on welshman.
Run an agent
The first run asks which identity the agent uses (a new key, an nsec, a
bunker:// link or a nostrconnect:// signer), its name, what it answers and
from whom, its relays, the model and its API key, and its instructions. It then
publishes the agent's relay list to the indexers, its direct message relays,
its profile and requests to join its rooms, and starts. Every run after that
starts it straight away.
| Command | |
|---|---|
npx @pi-nostr/cli |
Set up the first time, then start |
npx @pi-nostr/cli setup |
Ask the questions again, starting from the answers given |
npx @pi-nostr/cli sync |
Publish the relay lists, profile and room joins again |
npx @pi-nostr/cli start |
Start without asking anything |
npx @pi-nostr/cli status |
Say what is set up |
Everything is kept in ~/.pi-nostr, or the directory --dir or PI_NOSTR_HOME
names, and any file missing there is made with its defaults:
| File | |
|---|---|
config.json |
What it answers and from whom, the model, the instructions, the profile and the relays. Safe to edit by hand. |
account.json |
The identity: a key, or how to reach a remote signer. Readable by its owner alone. |
auth.json |
The model provider's credential, in pi's format, so the setup can copy pi's. Readable by its owner alone. |
session.sqlite |
The conversations, which a restart picks up without answering anything twice. |
A start whose identity has no relay list on the indexers syncs first, and a changed model or instructions reach the conversations already going.
| Package | For | What it does |
|---|---|---|
@pi-nostr/cli |
— | The program above, which runs the durable bridges below |
@pi-nostr/core |
both | The account (nsec or NIP-46 signer), a welshman app per account, the nostr operations, and every tool, defined once; /pi and /durable register them with each host |
@pi-nostr/pi-nip17 |
pi | The direct message tools, and the shared tools |
@pi-nostr/pi-nip29 |
pi | The room tools, and the shared tools |
@pi-nostr/pi-notes |
pi | The shared tools alone: notes, comments, profile and relay list |
@pi-nostr/durable-nip17 |
pi-durable | The same tools, plus a bridge that answers incoming direct messages |
@pi-nostr/durable-nip29 |
pi-durable | The same tools, plus a bridge that answers messages in rooms |
@pi-nostr/durable-notes |
pi-durable | The shared tools, plus a bridge that answers public mentions, replies and comments |
| Tools | |
|---|---|
| Shared | nostr_profile_read, nostr_profile_set (kind 0), nostr_relays_set (kind 10002, to the indexers), nostr_note_post (kind 1), nostr_comment_post (kind 1111), nostr_notes_read, nostr_replies_read, and nostr_publish_event, which signs and publishes any event |
| Direct messages | nostr_dm_relays_set (kind 10050), nostr_dm_send, nostr_dm_conversations, nostr_dm_read |
| Rooms | nostr_room_list, nostr_room_read, nostr_room_post, nostr_room_join, nostr_room_leave, nostr_room_members |
The pi packages only act when asked: answering whatever arrives is the durable bridges' job, since a durable conversation survives a restart and answers each message once.
Room moderation (kinds 9000–9008) is left out on purpose.
pi
Then, in pi:
/nostr-logintakes an nsec, abunker://link, or shows anostrconnect://link for a signer app. With a remote signer, only a client key is stored./nostr-login generatemakes a new key, kept only in the account file, and replacing or forgetting a key held there asks first./nostr-relays [urls...]publishes the account's relay list (kind 10002) to the indexers and the relays it names./nostr-dm-relays [urls...]publishes where it receives direct messages (kind 10050).
The agent treats the identity as its own, and knows to publish its relay list to the indexers before anything else; every publish says so while the list is missing.
Default relays
Where nothing is configured, the relays are the ones flotilla hands a new
account (core/src/relays.ts):
| Indexers | purplepag.es, relay.damus.io, indexer.coracle.social |
| Outbox, and fallback reads | relay.damus.io, relay.primal.net, nostr.mom |
| Direct messages | auth.nostr1.com, relay.keychat.io, relay.ditto.pub |
| Remote signer (nostrconnect) | ephemeral.snowflare.cc, bucket.coracle.social |
/nostr-relays, /nostr-dm-relays, nostr_relays_set and
nostr_dm_relays_set publish these when given no relays.
/nostr-whoamishows the account.
The account lives in ~/.pi/agent/nostr/account.json, or wherever
PI_NOSTR_ACCOUNT points. Both packages read the same file, and whichever loads
first registers the account commands and the shared tools.
Every write is signed and then published, and in a durable conversation what was signed is kept first, so a tool call rerun after a crash publishes the same event rather than a second one.
pi-durable
A pi-durable host installs each package's extension and starts its bridge:
- The NIP-17 bridge gives each set of participants its own conversation and
answers only the pubkeys in
from. Anybody can address a gift wrap to the account, sofrom: "anyone"hands the agent to every stranger. - The NIP-29 bridge gives each room one conversation.
mention: trueanswers only messages that mention the account, andfromnarrows who is answered. - The notes bridge listens on the read relays of the account's kind 10002 for
notes and comments that tag it, and answers those addressed to it: ones that
name it, start a thread tagging it, or answer one of its own events. A
reply elsewhere in a thread it once took part in tags it too, and is left
alone. Each thread is one conversation, comments on a thread's notes
included, and a note is answered with a threaded reply (NIP-10) and a
comment with a comment (NIP-22). Like direct messages,
fromis required, since anybody can tag the account. - Each answer is a durable task that submits the message, waits for the run, signs once and publishes until a relay takes it. A signer that is slow or offline delays a reply rather than losing it, and a restart resumes where it stopped.
@pi-nostr/cli is such a host, configured by its setup (packages/cli).
Development
The tests run against an in-memory relay and a NIP-46 signer in test/support,
and a faux model for the durable bridges. Workspace packages export their
sources under the @pi-nostr/source condition, which the tests and tsc use.
Waiting on welshman
These are worked around here and belong upstream:
- Relay-list lookups ask the indexers and configured relays directly, because
welshman's router drops
ws://and localhost relays (core/src/lists.ts). - Proof of work for gift wraps, mined to each relay's NIP-11
min_pow_difficulty, and delivery reported per recipient (core/src/nip17.ts);sendWrappedhas neither. - A publish that reports which relays accepted and refused, and a request held
open per relay that reconnects (
core/src/app.ts).