peerq

peerq is a durable, file-backed message queue for local agent sessions. It provides same-user, same-machine delivery without a broker or background daemon.

Features

• Stable UUID peer identities
• Transferable human-readable peer names
• Offline delivery through atomic filesystem operations
• Claim leases with renew, acknowledge, nack, and stale recovery
• Strict record validation and malformed-record quarantine
• JSON output for scripts and agent adapters
• No runtime dependencies

Requirements

• Go 1.22+
• Linux or macOS

Installation

go install github.com/Thelost77/peerq@latest

Ensure $(go env GOPATH)/bin or GOBIN is in PATH.

Storage

State defaults to:

$XDG_STATE_HOME/kumu/peerq

or, when XDG_STATE_HOME is unset:

~/.local/state/kumu/peerq

Set PEERQ_STATE_DIR to override the location.

Queue directories use mode 0700. Message and metadata files use mode 0600.

Usage

Register two sessions:

peerq register \
  --id 11111111-1111-4111-8111-111111111111 \
  --name implementation \
  --harness pi \
  --cwd "$PWD"

peerq register \
  --id 22222222-2222-4222-8222-222222222222 \
  --name review \
  --harness pi \
  --cwd "$PWD"

Names are aliases. Assigning an existing name transfers it to the latest registered session. Exact UUIDs remain canonical.

Queue a message without exposing its contents through process arguments:

printf '%s' 'Found a race in claim recovery.' | peerq send \
  --from 22222222-2222-4222-8222-222222222222 \
  --to implementation \
  --message-file - \
  --wake

Claim the oldest message:

peerq receive \
  --to 11111111-1111-4111-8111-111111111111 \
  --wait 30s

receive returns a claim and envelope as JSON. After the consumer persists delivery:

peerq ack --to <recipient-uuid> --claim <claim>

If delivery fails:

peerq nack --to <recipient-uuid> --claim <claim>

For long processing operations, renew the lease:

peerq renew --to <recipient-uuid> --claim <claim>

Other commands:

peerq peers
peerq inbox --to <recipient-uuid>
peerq remove --id <peer-uuid>

Run peerq help for the command list.

Delivery contract

• Sending means the envelope was synced and atomically queued.
• Receiving atomically moves one envelope into a processing claim.
• Consumers must acknowledge only after they persist delivery.
• Abandoned claims return to the inbox after the lease expires.
• Acknowledged claim files are deleted.
• Consumers should deduplicate by message UUID for at-least-once delivery.

Releases

Keep release notes in docs/releases/ and publish SemVer tags with a leading v:

./scripts/release.sh v0.1.0

License

MIT