Research: pi-messenger as Multi-Agent Coordination Reference

After deep-diving into nicobailon/pi-messenger, it turns out to be a strong reference implementation for the multi-agent collaboration spec requested here. Despite the name, it has nothing to do with iMessage/SMS — it's an inter-agent coordination system for the Pi coding agent that enables multiple AI agent instances to discover each other, communicate, reserve files, and orchestrate parallel work.

Here's what it does and how its patterns could map to Hermes Agent:

How pi-messenger Works

Pi-messenger is a TypeScript extension for the Pi coding agent. It enables multiple Pi agent instances running in separate terminals to collaborate on a shared codebase via file-based coordination (no server/daemon required).

Core subsystems:

Subsystem	How It Works	Hermes Equivalent
Agent Registry	Each agent writes a JSON file to `~/.pi/agent/messenger/registry/<Name>.json` with PID, status, capabilities. Dead agents auto-cleaned via PID checks.	No equivalent — agents don't know about each other
Inter-agent Messaging	Messages are JSON files written to `~/.pi/agent/messenger/inbox/<Name>/`. A `fs.watch()` monitors the inbox and injects received messages as steering prompts (`triggerTurn: true`). Supports DMs + broadcast.	No equivalent — subagents can't communicate during execution
File Reservations	Agents call `reserve --path <file>` before editing. Other agents see the lock and skip that file. Prevents merge conflicts in multi-agent coding.	No equivalent — concurrent subagents can step on each other's files
Activity Feed	Append-only JSONL log at `~/.pi/agent/messenger/feed.jsonl`. All agent actions (join, send, reserve, complete) are logged with timestamps.	No equivalent
Crew Orchestration	`plan` command parses a PRD/task description into a dependency graph of subtasks, assigns them to agents in parallel waves, handles review cycles. Phases: plan -> work -> review.	Partially covered by `delegate_task` (fire-and-forget parallel subtasks, but no dependency graphs, no review cycle)
Stuck Detection	Monitors agents that haven't acted recently. Can nudge or reassign work.	No equivalent
Scratchpad/Status	Each agent can set a status message visible to others ("working on X", "blocked on Y").	No equivalent

The single tool interface: Agents interact through one tool — pi_messenger({ action, ...params }) — which dispatches to handlers for join, send, list, reserve, release, broadcast, plan, work, review, etc.

What Hermes Already Has vs. The Gap

Current state (delegate_tool.py):

Ephemeral subagents: spawn, execute task, return summary, die
No inter-agent communication during execution
No agent discovery (parent knows children, but children don't know siblings)
No file locking (concurrent children can conflict)
No dependency-aware orchestration (all tasks fire in parallel)
Max 3 concurrent, max depth 2

The gap pi-messenger reveals:

No persistent agent collaboration — Hermes can delegate tasks but can't coordinate persistent agents that work alongside each other
No file safety — Two subagents editing the same file will conflict silently
No inter-agent messaging — A subagent that discovers critical context can't share it with a sibling
No structured orchestration — No way to express "do A and B in parallel, then C when both finish, then D reviews all of it"

Proposed Implementation for Hermes Agent

Classification

This would be a codebase change (enhancements to delegate_tool.py and possibly a new coordination_tool.py), not a skill or standalone tool. The coordination primitives need to be deeply integrated with the agent lifecycle.

Phase 1: File Reservations (Immediate Value, Low Effort)

Add file-level locking to prevent subagent conflicts. This is the lowest-hanging fruit with the highest impact.

# In delegate_tool.py or a new coordination module
class FileReservation:
    """Simple file-based locking for multi-agent file editing."""
    LOCK_DIR = "~/.hermes/locks/"
    
    def reserve(self, path: str, agent_id: str) -> bool: ...
    def release(self, path: str, agent_id: str) -> None: ...
    def check(self, path: str) -> Optional[str]: ...  # Returns holding agent_id

Before a subagent writes to a file, check if another agent holds it
Auto-release on agent completion/crash
PID-based cleanup for stale locks
Could integrate with the existing write_file and patch tools transparently

Phase 2: Inter-Agent Messaging (Medium Effort)

Enable sibling subagents to share discoveries during execution.

Approach A — File-based (like pi-messenger):

Each subagent gets an inbox directory
Messages are JSON files watched via filesystem events
Simple, no server needed, but same-machine only

Approach B — Shared queue (more Hermes-native):

Parent agent holds a queue.Queue() per child
Children can call send_to_sibling(agent_id, message) tool
Parent relays messages between children during their execution
Works across any terminal backend (local, Docker, Modal, SSH)

Approach B is more aligned with Hermes's architecture since subagents already share the parent process.

Phase 3: Structured Task Orchestration / Crew System (Higher Effort)

Extend delegate_task to support dependency graphs:

delegate_task(
    workflow=[
        {"id": "research", "goal": "Research the API docs", "context": "..."},
        {"id": "backend", "goal": "Implement the backend", "depends_on": ["research"]},
        {"id": "frontend", "goal": "Build the UI", "depends_on": ["research"]},
        {"id": "review", "goal": "Review and integrate all work", "depends_on": ["backend", "frontend"]},
    ]
)

Tasks with no dependencies run in parallel
Tasks with dependencies wait for upstream completion
Each downstream task receives upstream results as context
Optional "review" step that can send work back for revision

Phase 4: Persistent Named Agents (Stretch — addresses @archasek's request)

Enable long-running named agents with distinct identities:

Agent registry: named agents register with role, capabilities, status
Cross-platform routing: "research agent" in Discord channel #research, "ops agent" in #ops
Inter-agent delegation: one agent can delegate to another by name
Shared memory boundaries: agents share a codebase but have separate conversation histories
This maps directly to @archasek's request for "specific agents in different discord channels"

This is the most ambitious phase and would require changes to the gateway session management to support multiple agent identities per gateway instance.

Pros & Cons

Pros:

Directly addresses the multi-agent collaboration gap (Multi-agent support #299)
File reservations alone would prevent a real class of bugs in parallel subagent work
pi-messenger is a proven, working implementation of these patterns (MIT licensed)
Phased approach: each phase delivers value independently
Phase 1-2 are relatively low effort with high impact

Cons:

pi-messenger's code is TypeScript and Pi-specific — patterns are portable but code isn't
File-based coordination is same-machine only (fine for local/Docker, not for Modal/SSH unless adapted)
Crew orchestration adds complexity to the delegate_task interface
Persistent named agents would require significant gateway architecture changes
Risk of over-engineering: most users may be fine with current fire-and-forget delegation

References

nicobailon/pi-messenger — Working reference implementation (TypeScript, MIT)
Pi coding agent — The agent system pi-messenger extends
Nico Bailon — Author (Vancouver-based developer, prolific Pi extension builder)
Current Hermes: tools/delegate_tool.py — Existing subagent architecture

Multi-agent support #299

Description

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions