A file-based (Maildir-style) message queue for local agent-to-agent communication — zero infrastructure, crash-safe, providing the missing coordination layer for multi-agent development.
Agent Message Queue (AMQ) is a local message queue system designed for AI agent collaboration. It implements a Maildir-style file-based approach with zero infrastructure requirements — no servers, daemons, or databases needed.
Key Features#
- Zero Infrastructure: Pure filesystem implementation, runs anywhere with a filesystem
- Crash-Safe: Maildir atomic delivery mechanism (tmp→new→cur), messages never lost or partially written
- Human-Readable: JSON frontmatter + Markdown body format, viewable with
cat, debuggable withgrep, version-controllable withgit - Real-time Notifications:
amq wakeinjects terminal notifications when messages arrive (experimental) - Agent Collaboration Primitives: Priority levels, message types, thread tracking, acknowledgment mechanism
Message Types & Priority#
Supports 8 message types: review_request, review_response, question, answer, decision, brainstorm, status, todo
Three priority levels: urgent (immediate response), normal (add to todo list), low (batch processing)
Collaboration Modes#
- Leader + Worker: Leader decides, Worker executes (default)
- Co-workers: Equal collaboration, escalate to originator on disagreement
- Duplicate: Independent solutions/reviews, originator merges results
- Driver + Navigator: Driver codes, Navigator reviews/tests with interrupt capability
- Spec + Implementer: One writes specs/tests, other implements
- Reviewer + Implementer: One codes, other focuses on review and risk detection
Installation#
# macOS (Homebrew)
brew install avivsinai/tap/amq
# macOS/Linux (Script)
curl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash
Quick Start#
# Initialize project
amq coop init
# Send message
amq send --to codex --subject "Review needed" --kind review_request --body "Please review internal/cli/send.go"
# List inbox
amq list --new
# Read messages
amq drain --include-body
Core CLI Commands#
| Command | Description |
|---|---|
amq init | Initialize queue |
amq send | Send message |
amq list | List messages |
amq read | Read specific message |
amq drain | Read all and move to cur |
amq reply | Reply to message |
amq watch | Block until message arrives |
amq wake | Background terminal notifications |
amq coop exec | Start collaboration session |
amq swarm join/claim/complete/bridge | Swarm mode commands |
Architecture#
Built with Go, core modules include:
internal/fsq/: Filesystem queue (Maildir delivery, atomic operations)internal/format/: Message serializationinternal/swarm/: Claude Code Agent Teams interoperabilityinternal/thread/: Cross-mailbox thread collection
Mailbox layout follows Maildir standard: <root>/agents/<agent>/inbox/{tmp,new,cur}/
Scope & Limitations#
- Suitable for: Single-machine environments with 2-3 agents
- Not suitable for: Distributed/cross-machine agent communication
- Platform support: macOS, Linux, Windows (WSL)