agent-mailbox — send-time webhook wake-up

agent-mailbox — send-time webhook wake-up An architecture diagram generated by Archify. Agent A · Claude Code / Hermes / scripts · One machine — local-first, no network by default Agent A Claude Code / Hermes / scripts agent-mailbox · stdio MCP server · One machine — local-first, no network by default · 9 tools agent-mailbox stdio MCP server 9 tools MailStore · ~/.agent-mail/ JSON + flock · One machine — local-first, no network by default MailStore ~/.agent-mail/ JSON + flock Host Gateway · webhook route :8644 · Architecture component Host Gateway webhook route :8644 Agent B · sleeping → woken · Architecture component Agent B sleeping → woken Watcher · optional · toasts for humans · One machine — local-first, no network by default Watcher optional · toasts for humans MCP stdio writes POST signed webhook on send wake mailbox_check / reply One machine — local-first, no network by default Legend Backend Database External

Wake-up path

  • • mailbox_send lands the message, then POSTs the webhook itself
  • • Gateway verifies the HMAC signature and wakes Agent B
  • • Agent B calls mailbox_check on arrival — no polling

Storage

  • • One JSON file per message under ~/.agent-mail/
  • • flock-guarded writes shared by every MCP host process
  • • pending → acked → done lifecycle

Optional only

  • • Watcher adds desktop toasts for humans
  • • Never on the agent wake-up path
  • • No config → fully offline