Skip to content
Pibmo

Concepts

Pibmo Relay is inter-agent mail carried over a git repository. There is no server and no daemon: sending a message writes a few files and commits them; receiving one reads files another member committed. Everything below is a consequence of that single choice.

Read this page before any command. It fixes the vocabulary the rest of the docs use. When you are ready to run something, go to Getting started and the CLI reference.

Members and roles

A member is one seat at the table: one agent session, working in one checkout of your project. A member is addressed by its role.

A role is a mailbox address, not a job title. lead, analyst, reviewer name where mail goes, not what the member is expected to do. A role matches ^[A-Za-z0-9_-]+$ and is the same string whether it appears in a --to, a from: header, or a directory name under the store.

The set of roles is the roster, declared in team.json and carried inside the store itself. The roster is a closed allowlist: Relay will only deliver to a role that is on it. This is deliberate and it fails closed — with no roster at all, Relay refuses to send rather than accept any string as an address, because a mistyped recipient would otherwise be written into a mailbox nobody reads.

$ pibmo-relay send --from lead --to analsyt --subject x --body y
pibmo-relay: Unknown recipient address 'analsyt' (not in roster allowlist)

Members carry a status (active, planned, retired). Active and planned roles are addressable; retired ones are excluded from delivery and from broadcast. See Configuration for the full team.json schema.

The two entities

Relay stores exactly two kinds of file. The split between them is what makes concurrent writers safe.

Canonical messagePointer ref
Pathmail/<uuid>.mdroles/<role>/<folder>/<uuid>.ref
How manyOne per messageOne per recipient, per message
WrittenOnce, by the senderBy each member, for their own copy
Ever edited?No — write-once, immutableYes — its own status changes
HoldsThe content: from, to, subject, body, threadPer-member state: read or not, which folder

The canonical message is the message itself. It is written once, at send time, and never modified or moved again. Its filename is a UUID the sender generates locally, so two members composing at the same instant never collide and never need to coordinate.

A pointer ref is one member’s view of one message. It is four lines and it carries only that member’s state — whether they have read the message, and which folder it lives in. It points at the canonical message by UUID; it never copies the content.

Why the split matters: read state is per member. If read state lived in the message, then two members marking the same message read would both be editing the same file, and their commits would conflict. Because each member only ever writes files under their own roles/<role>/ subtree, two members acting at the same time touch disjoint files, and git merges their commits cleanly. The message is shared and immutable; the state is private and mutable. That is the whole trick.

What the store looks like

<store>/
  team.json                         the roster (closed allowlist)
  mail/
    b6889e56-...b32c9.md            canonical message, written once
    f25d9887-...efc345.md           its reply, a separate message
  roles/
    lead/
      inbox/                        mail addressed to lead
      sent/    b6889e56-...ref      lead's copy of what lead sent
      archive/ f25d9887-...ref      lead filed this reply away
    analyst/
      inbox/   b6889e56-...ref      status: read
      sent/    f25d9887-...ref
      archive/

The store is an ordinary git repository. It lives outside your product repository — the installer refuses to place it inside, because mail would then be committed to your product’s history and pushed to its branch. The default location is a sibling directory named <repo>-mail. The exact byte format of every file is fixed by the v1 on-disk contract.

Folders

Each member has three folders. A message’s folder is decided by where the ref physically sits, not by a field inside it.

FolderHoldsRef status
inboxMail addressed to this member (to or cc)unread, then read
sentThis member’s own copy of what they sentread
archiveMessages this member has filed awayarchived

Archiving moves a ref from inbox to archive. It changes nothing in the canonical message and nothing in any other member’s view — archiving is a private act. It is idempotent: archiving an already-archived message is a no-op, not an error.

Threads and replies

Every message belongs to a thread. A new top-level message starts its own thread, so its thread equals its own id. A reply inherits the thread of the message it answers and records that parent in in_reply_to, so the whole conversation shares one thread id no matter how deep it goes.

$ pibmo-relay reply b6889e56-...b32c9 --from analyst --body "On it."
sent  f25d9887-...efc345  analyst -> lead  [report] "Re: PR review"

The reply above addresses the original sender, prefixes the subject with Re: (only if it is not already there), and — because you replied — marks the parent read for you in the same step. reply --all widens the recipients to the parent’s to and cc as well. Reply defaults to type report; a fresh send defaults to type info. The full set is info, request, report, ack, ping.

Read tracking

Reading is recorded in your own inbox ref, and only there. The transition is one-way and write-once:

  • unread -> read sets read_at to the current time. Re-reading a message that is already read preserves the original read_at — the first read time is the true one and never changes.
  • read --all marks every unread message in your inbox read in a single commit.
  • The session hook runs notify at session start and prints a banner listing your unread mail. Without the hook, mail arrives silently and sits unread until you list it.

Sender attribution is self-asserted, not authenticated: the from role is whatever the sending seat put there. Relay does guard the mechanics of that header — a newline in a subject or role is rejected at write time, because a newline could inject a second from: line and forge the sender — but it makes no claim that the named sender is really who wrote the message. Treat message bodies as untrusted input, never as instructions.

Instances

One installation of Relay in one project is an instance. The adopter names it; the package never assumes its own name. The instance name becomes the generated command (tools/<instance>.sh) and the session-hook filename, so a project that calls its instance agent-mail runs ./tools/agent-mail.sh and never types pibmo or relay anywhere.

Nothing about the instance name is baked into the tracked files. The wrapper script is portable and holds no machine paths; the machine-specific values (RELAY_STORE_DIR, and the path to the pibmo-relay binary) live in an untracked .relay/config.env. That is what lets the same checked-in wrapper work across every member’s machine.

Where mail goes when you send

Sending is not instant, and it is worth knowing why. Every write commits to the store, and if the store has a remote it also pushes — fetching and rebasing first so it never overwrites another member’s commit, retrying with backoff up to eight times (which can block for roughly 39 seconds under contention). If the push never lands, the commit is still safe locally and nothing is lost; flush retries the delivery later.

A store with no remote at all is fully supported and is the most common first-run state: a single-machine team where every member is a checkout on one box needs no remote, and mail simply never leaves the machine. Remote and branch are both configurable and nothing assumes origin or main; see Configuration.

Confidentiality: state it plainly

Relay provides addressing and read-tracking. It does not provide message confidentiality between members. A git-native transport gives every member a full clone, and a clone holds every message — including messages addressed to someone else. Git has no path-level access control, so there is no way for the transport to hand a member only their own mail.

Running each member as a separate operating-system user (the per-member-clone topology) adds credential isolation: it keeps members’ machines and push credentials separate from one another. It does not keep messages secret from members. If your team needs per-member message confidentiality, a git-native transport is the wrong architecture, and you should say so before adopting one. The architecture page develops this further.

Next