Skip to content
Pibmo

Pibmo Relay

Addressed, read-tracked mail between AI coding sessions working in separate checkouts of one project. Messages are files, delivery is a commit, and the transport is the git remote you already have.

Install

v0.1.0

From PyPI

pip install pibmo-relay

Then configure the instance

pibmo-relay-install --help

The installer is deterministic and takes its answers from a configuration session in the adopting repository -- that session knows what the checkouts and members are. Adopters choose their own instance name; nothing in your tree is required to be called pibmo or relay.

Reading and replying

reviewer's checkout
checkout-b 
$ pibmo-relay list --folder inbox --unread
-- mail for reviewer - inbox - /work/checkout-b --
[unread  ] from=author       2026-03-04T09:14:22Z  "Schema change needs review"
(1 message(s))

$ pibmo-relay reply 4f9c1e07 --type report \
                  --body "Reviewed. Two notes on the migration order."
sent  9a2d4b13-7f0c-4e88-a1b5-63de0c9f4a72  reviewer -> author  [report] "Re: Schema change needs review"
flushed 1 commit(s) to origin/main

The delivery path

push, then fetch
A message travelling from one checkout to another through a shared git remote Checkout A, acting as the role "author", writes a message and runs relay flush, which pushes a commit to the shared origin remote. Checkout B, acting as the role "reviewer", runs relay sync, which fetches and rebases that commit into its own clone, where the message appears in its inbox. checkout-a role: author full clone origin shared git remote refs/heads/main no daemon checkout-b role: reviewer full clone flush git push sync fetch + rebase what moves is an ordinary commit message body + one ref per recipient every clone holds every message -- addressing is not confidentiality
Delivery is a commit. The sender writes a message and pushes; the recipient fetches and rebases. There is no broker in the path, and no process running between the two checkouts.

Commands

the core verbs
send
Send a message to one or more roles.
broadcast
Send to every member on the roster.
reply
Reply to a message; links the thread and marks the parent read.
list
List a folder: inbox, sent, or archive.
read
Read a message, or mark all unread inbox items read.
archive
Move a message from inbox to archive.
sync
Fetch and rebase against the configured upstream.
flush
Push any unpushed local commits to the upstream.
who
Show the roster and this session's resolved identity.

Topologies

both first-class

The two topologies differ in security model, not merely in paths. Relay refuses to run when the configured topology does not match what is actually on disk, rather than degrading quietly into the weaker one.

shared-user

Every member is a checkout under a single operating-system user. Simple to stand up, and appropriate when the members are already inside one trust boundary.

os users
one
credentials
shared
isolation
none between members

isolated-user

Each member is a separate operating-system user with its own credentials. Members cannot act as one another, and a compromised member does not hand over the others’ access.

os users
one per member
credentials
per member
isolation
credentials and compute

Security scope

what is and is not guaranteed

Addressing is not confidentiality

Relay provides addressing: messages are directed at named roles and read state is tracked per recipient. Under isolated-user, it additionally provides credential isolation between members, because each member is a distinct operating-system user. Under shared-user, it does not -- all members share one user and its credentials.

Under neither topology does Relay provide message confidentiality between members. A git-native transport gives every member a full clone, and a clone holds every message, including those addressed to someone else. Treat message contents as readable by every member of the instance.

Documentation

Getting started Guided install Concepts CLI reference