---

The problem

Every pi session is an isolated process. Run three in parallel — three bug-bounty hunts, three features, three refactors — and they're strangers: they duplicate each other's work, forget what the others learned, and die with their knowledge.

armory-mesh gives them a shared nervous system:

• Presence — each session sees the fleet live: who's running, on what model, how much context is left, what they're claiming. A session that dies is evicted automatically — no ghosts.
• Claims — atomic work claims (mesh_claim_target) so two sessions never hunt the same target. A losing claimant is told no, and who holds it.
• Duplicate checks — mesh_dup_check sweeps the pool: "has anyone seen this bug?" Every peer answers from its ledger in seconds. An overlap reply is a duplicate submission saved.
• Durable memory — findings banked at 02:00 with nobody online are replayed to whoever joins at 09:00. The fleet-state ledger (fleet-state.jsonl) survives every session.

Quickstart

# user scope — available in every project, no trust prompt
pi install npm:@getpipher/armory-mesh

# or project scope — lives in .pi/settings.json, shared with the repo;
# pi auto-installs it on next start once you trust the project
pi install -l npm:@getpipher/armory-mesh

# a local checkout works too
pi install /path/to/armory-mesh

The npm: prefix is required — a bare package name parses as a local path and fails.

Then fire your sessions. Each one prints the join line and grows a live fleet widget below the editor:

📡 mesh: joined "my-project" as agent-2cc1e9

mesh bug-bounty-fleet · 6 peers
  gmtrade-audit   glm-5.3-flash  ctx:34%  ⟨gmtrade⟩  1s
  veilo-recon     glm-5.3-flash  ctx:10%             1s
  hunter-3        glm-5.3-flash  ctx:67%             0s
  … +3 more peers

Presence updates every 2 seconds (name, model, live context-window usage, claimed target, last-seen). The widget collapses past PI_MESH_WIDGET_MAX_ROWS (default 10), most-recently-active first.

Running a session you don't want in the mesh at all? PI_MESH_OFF=1 pi … — the package stays installed, but that session registers no mesh surface (no tools, no widget, no socket, no key).

Who can see whom: a session joins the pool named by — in order of precedence — the PI_MESH_PROJECT env var, a .pi/mesh.json anywhere up its folder tree, or its working folder's basename. Same pool = visible to each other. Different pool = complete strangers. Knowledge itself only moves when a session calls a tool — presence metadata (heartbeats) is the only automatic traffic.

The tools (injected into every session)

Tool	What it does
mesh_list	Live peers: name, model, host, context usage, claimed target, last-seen
mesh_send	Send a typed message to a peer or a channel
mesh_get / mesh_await	Pull (fire-and-forget) or block for matching messages
mesh_claim_target / mesh_release_target	Atomic work claims (filesystem-lock) — stale claims from dead sessions are auto-reclaimable
mesh_bank_finding	Announce + permanently persist a finding
mesh_dup_check	"Has anyone seen this?" — every peer answers from its ledger in seconds
mesh_handoff	Publish a resume pointer for the next session
mesh_fleet_state	Read the durable ledger (claims, findings, dup-checks, handoffs)
mesh_channels	Channels + live subscriber counts

Slash commands for the human at the keyboard: /mesh (pool status) and /mesh doctor (full install + runtime diagnostics — wiring, trust, key, transport, peers, claims, ledger).

The workflow it enables

1. Claim before you start — mesh_claim_target("gmtrade"). A duplicate claimant is told no, and who holds it.
2. Bank at milestones — mesh_bank_finding(...) writes through to fleet-state.jsonl and broadcasts on #dup-check. Even with zero peers online, it's durable.
3. Check before you submit — mesh_dup_check(...) sweeps the fleet. An overlap reply is a duplicate submission saved.
4. Handoff on exit — mesh_handoff(...) so the next session resumes instead of restarting.

How it works

• Same machine: each session listens on a private Unix socket (~/.pi/mesh/<project>/sockets/<id>.sock, 0600). Sending = connect → write one length-prefixed JSON frame → ack → close.
• Cross-machine: a small hub relays over HTTP + SSE.
• Unreachable peer? Mesh relay: a peer that can reach the destination forwards the frame — with a visited-set + hop-count so loops are impossible.
• Persistence: senders write through to per-channel logs (local: shared ndjson; hub: a disk-backed store under ~/.pi/mesh/ that survives hub restarts) — the durable ledger (fleet-state.jsonl) is always written.

Security (by default, even on localhost)

• Project key — 32 random bytes per pool (~/.pi/mesh/<project>/key, 0600). Every message is HMAC-SHA256 signed over a canonical encoding; receivers verify with a timing-safe compare and drop forgeries.
• Replay protection — per-sender monotonic nonces; a captured frame can't be re-injected.
• Hub LAN gate — the hub requires its own token and never sees the project key; it's a dumb relay, messages stay end-to-end signed.
• Flood caps — per-message size cap (256 KB), per-channel rate cap (10 msg/s), bounded queues.
• Full threat model + residual risks: SECURITY.md.

Cross-machine: the hub

# machine A — the hub (one process, no deps)
PI_MESH_AUTH_TOKEN=<secret> PI_MESH_HUB_PORT=7399 npx jiti src/hub.ts

# machine B — point sessions at it (and copy the project key across)
PI_MESH_HUB_URL=http://<A>:7399 PI_MESH_AUTH_TOKEN=<same-secret> pi

The hub holds the cross-machine registry, relays messages, and keeps bounded per-channel history for late-joiner replay — on disk, so a hub restart no longer wipes the catch-up history (PI_MESH_STORE_PATH to relocate, =off for memory-only). Clients fail over automatically across PI_MESH_HUB_URLS (comma-separated) if the primary dies — and a reconnect back-fills exactly the messages missed while the stream was down (proven by the reconnect smoke). Run the hub on infrastructure you trust; terminate TLS in front of it if it leaves the LAN.

Project-scoped pools

Drop a .pi/mesh.json at any workspace root and every session fired under it joins the same pool — regardless of which subfolder it was launched from:

{
  "project": "my-fleet",
  "persistChannels": ["#dup-check", "#handoff", "#general", "#learnings"]
}

Precedence: PI_MESH_PROJECT env → nearest .pi/mesh.json → folder basename.

Configuration (env)

Variable	Default	Meaning
PI_MESH_OFF	—	Per-session opt-out: 1/true/yes/on → this session registers no mesh surface (package stays installed)
PI_MESH_PROJECT	folder basename	Pool id
PI_MESH_AGENT_NAME	random	Readable name in the widget
PI_MESH_HUB_URL / PI_MESH_HUB_URLS	—	Hub endpoint(s) — cross-machine mode
PI_MESH_AUTH_TOKEN	—	Required for hub mode
PI_MESH_STORE_PATH	~/.pi/mesh/hub-store.ndjson	Hub replay store (set off for memory-only)
PI_MESH_PING_MS / PI_MESH_EVICTION_MISSES	2000 / 5	Heartbeat interval / eviction window
PI_MESH_MAX_MESSAGE_BYTES	262144	Per-message cap
PI_MESH_CHANNEL_RATE_PER_SEC	10	Per-channel send-rate cap
PI_MESH_MAX_HOPS	8	Mesh-relay hop limit
PI_MESH_WIDGET_MAX_ROWS	10	Pool-widget peer rows before collapsing into "… +K more"
PI_MESH_PERSIST_CHANNELS	#dup-check,#handoff,#general	Channels with durable logs

Why not just use coms?

coms (disler) pioneered peer-to-peer pi messaging — armory-mesh is the hardened evolution.

	coms	armory-mesh
Pool size	N peers	N peers (bounded relay + caps)
Auth	—	project key + HMAC-signed frames, even on localhost
Replay protection	—	monotonic nonces, timing-safe verify
Liveness	keepalive pings	signed heartbeat gossip + auto-eviction (no ghosts)
Messages	text lines	typed messages + subscription-scoped channels
Persistence	—	send-through logs + late-joiner replay + durable fleet ledger
Fleet primitives	—	claim / bank / dup-check / handoff, built in
Cross-machine	separate codepath	unified transport: sockets ↔ hub, with failover + relay
Abuse limits	line cap	256 KB per-message + 10 msg/s per-channel caps + mesh relay loop prevention

coms is a great chat wire; armory-mesh is a fleet operating layer.

Status

🚀 v0.1.x — built and hardened through 12 smoke-tested suites (transport, liveness, channels, persistence, fleet-state, hub, relay/failover/replay, hardening, wiring, diagnostics, reconnect), running in a live multi-session security-hunting fleet. API may still shift before 1.0.

• DESIGN.md — architecture + the hardened guarantees
• ROADMAP.md — build phases
• SECURITY.md — trust models + residual risks

License

MIT