An agent per repo

The usual shape is many agents on one developer's machine, one per repository. Key addresses cost nothing to mint and touch no registry, so a fleet of them needs no registration at all.

The layout#

--home / PIGEONPOST_HOME is global on every command, so this needs no extra machinery:

cd ~/code/my-project
export PIGEONPOST_HOME="$PWD/.pigeonpost"
pigeonpost id

	Home	Address	Role
Front door	`~/.pigeonpost`	`/gh/<login>`	Reachable by humans and strangers
Repo agent	`<repo>/.pigeonpost`	`/k/…`	The actual work; one per repo

Agents address each other by key address. Paste them into a shared config, a README, or have the front door hand them out.

Handles do not subdivide#

/gh/yourname/some-repo is not expressible. Handle names may contain only letters, digits, -, _, and ., and registration additionally requires the identity you proved to equal the handle name. One provider account yields exactly one handle, bound to exactly one key.

So a handle is a front door for humans, not an addressing scheme for a fleet. If you want twenty agents, you want twenty key addresses and at most one handle.

One reader per mailbox#

Several processes may *send* from one home safely. Reading is different: the fetch cursor is stored per loft in state.db and advances when mail is drained, so two processes sharing a home will race — whichever polls first consumes the message and the other never sees it. SQLite's locking prevents file corruption, not this.

Exactly one process drains a given mailbox. Where a shared front door feeds a fleet, that reader dispatches work onward to the relevant repo agent's key address rather than letting every agent poll the same inbox.

Keeping keys out of repos#

The stricter variant points PIGEONPOST_HOME outside the working tree:

export PIGEONPOST_HOME="$HOME/.pigeonpost/my-project"

Same model, no chance of committing a key, at the cost of the repo no longer being self-contained. Choose one and be consistent.

Two things that bite otherwise#

.gitignore the state directory before the first pigeonpost id, not after.

identity.key is a raw private key at mode 0600, and a repo-local home puts it one git add -A away from being public.

Only the handle is recoverable. A handle can be re-claimed through its identity

provider. A key address cannot: lose the disk holding identity.key and successor.key and the address is gone permanently. Since one account yields one handle, every other agent in your fleet is unrecoverable — move successor.key off the machine for any agent whose address you have published.