personal-agent-os/agent-comms/protocol.md

Agent Communication Protocol v2 — Message Queue

This replaces the manual relay protocol. Messages are standalone files with structured frontmatter — no SHA conflicts, no append-only bloat.

Directory Structure

agent-comms/
├── protocol.md                    ← This file
├── leonard-outbox/                ← Leonard → Grok messages (Grok reads via MCP)
└── grok-inbox/                    ← Grok → Leonard messages (written via `grok_send_message` MCP tool, read by Leonard)

File Format

agent-comms/leonard-outbox/{seq}-leonard-to-grok-{topic-slug}.md
agent-comms/grok-inbox/{seq}-grok-to-leonard-{topic-slug}.md

Frontmatter

---
from: leonard          # or "grok"
to: grok               # or "leonard"
status: pending        # pending | read | responded
seq: 1                 # auto-incrementing sequence number
topic: topic-slug
reply_to: 2            # optional: the seq this message is responding to
timestamp: 2026-06-26T05:30:00Z
---

How Each Agent Reads/Writes

Leonard (Hermes Agent)

Reads from: grok-inbox/ Writes to: leonard-outbox/

1. Lists files in grok-inbox/ sorted by sequence
2. Checks for status: pending messages
3. Sets status: read after first processing
4. Responds by writing to leonard-outbox/ with reply_to: <seq>

Grok

Reads from: leonard-outbox/ Writes to: grok-inbox/ via the grok_send_message MCP tool on Hermes MCP server (:8092)

1. Lists files in leonard-outbox/ via MCP list_directory or gitea_read_file
2. Reads pending messages
3. Calls grok_send_message tool with:
   • topic: short slug
   • content: full markdown body
   • reply_to: sequence being responded to

Workflow

1. Leonard writes a task → leonard-outbox/0001-leonard-to-grok-lets-build-x.md
2. Grok detects new file (via MCP list_directory), reads it
3. Grok calls grok_send_message(topic="responding", content="...", reply_to="1")
4. Cron job on Leonard's side detects new grok-inbox/ file
5. Leonard reads and processes Grok's response
6. Loop continues

Cron Watcher (Leonard Side)

A cron job runs every 5 minutes and checks:

• grok-inbox/ for new status: pending messages
• When a new message is found: logs it, sets status to read, and triggers a response cycle

Security

• Messages are public (the repo is public)
• Do not put secrets, API keys, or credentials in messages
• The grok_send_message MCP tool uses the Gitea token from the server environment