Coordinate agents via the AMQ CLI for file-based inter-agent messaging. Use when you need to send messages to another agent (Claude/Codex), receive messages from partner agents, set up co-op mode between Claude Code and Codex CLI, or manage agent-to-agent communication in any multi-agent workflow. Triggers include "message codex", "talk to claude", "collaborate with partner agent", "AMQ", "inter-agent messaging", or "agent coordination".
/plugin marketplace add avivsinai/agent-message-queue/plugin install amq-cli@avivsinai-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/coop-mode.mdreferences/message-format.mdFile-based message queue for agent-to-agent coordination.
Requires amq binary in PATH. Install:
curl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash
Verify: amq --version
# Set once per session - commands work from any directory
export AM_ROOT=.agent-mail AM_ME=claude # or: AM_ME=codex
amq send --to codex --body "Message" # Send
amq drain --include-body # Receive (recommended)
amq reply --id <msg_id> --body "Response" # Reply
amq watch --timeout 60s # Wait for messages
amq list --new --priority urgent # Filter messages
Note: With env vars set, all commands work from any subdirectory.
In co-op mode, agents work autonomously. Message your partner, not the user.
Both agents work in the same project folder. Files are shared automatically:
Only use messages for: coordination, questions, review requests, status updates.
| Situation | Action |
|---|---|
| Blocked | Message partner |
| Need review | Send kind: review_request with file paths |
| Partner done | Read files directly (they're local) |
| Done | Signal completion |
| Ask user only for | credentials, unclear requirements |
Run once per project:
curl -sL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/setup-coop.sh | bash
export AM_ROOT=.agent-mail AM_ME=claude # or: codex
Start a background waker before your CLI to receive notifications when messages arrive:
amq wake &
claude
When messages arrive, you'll see a notification injected into your terminal (best-effort):
AMQ: message from codex - Review complete. Run: amq drain --include-body
Then run amq drain --include-body to read messages.
Inject Modes: The wake command auto-detects your CLI type:
--inject-mode=auto (default): Uses raw for Claude Code/Codex, paste for others--inject-mode=raw: Plain text + CR (best for Ink-based CLIs like Claude Code)--inject-mode=paste: Bracketed paste with delayed CR (best for crossterm CLIs)If notifications require manual Enter, try --inject-mode=raw.
| Priority | Action |
|---|---|
urgent | Interrupt, respond now |
normal | Add to TODOs, respond after current task |
low | Batch for session end |
amq send --to codex --body "Quick message"
amq send --to codex --subject "Review" --kind review_request --body @file.md
amq send --to claude --priority urgent --kind question --body "Blocked on API"
amq send --to codex --labels "bug,parser" --body "Found issue in parser"
amq send --to codex --context '{"paths": ["internal/cli/"]}' --body "Review these"
amq drain --include-body # One-shot, silent when empty
amq watch --timeout 60s # Block until message arrives
amq list --new # Peek without side effects
amq list --new --priority urgent # By priority
amq list --new --from codex # By sender
amq list --new --kind review_request # By kind
amq list --new --label bug --label critical # By labels (can repeat)
amq list --new --from codex --priority urgent # Combine filters
amq reply --id <msg_id> --body "LGTM"
amq reply --id <msg_id> --kind review_response --body "See comments..."
amq dlq list # List failed messages
amq dlq read --id <dlq_id> # Inspect failure details
amq dlq retry --id <dlq_id> # Retry (move back to inbox)
amq dlq retry --all [--force] # Retry all
amq dlq purge --older-than 24h # Clean old DLQ entries
amq upgrade # Self-update to latest release
amq --no-update-check ... # Disable update hint for this command
export AMQ_NO_UPDATE_CHECK=1 # Disable update hints globally
amq thread --id p2p/claude__codex --include-body # View thread
amq presence set --status busy --note "reviewing" # Set presence
amq cleanup --tmp-older-than 36h # Clean stale tmp
| Kind | Reply Kind | Default Priority | Use |
|---|---|---|---|
review_request | review_response | normal | Code review |
review_response | — | normal | Review feedback |
question | answer | normal | Questions |
answer | — | normal | Answers |
decision | — | normal | Design decisions |
brainstorm | — | low | Open discussion |
status | — | low | FYI updates |
todo | — | normal | Task assignments |
Labels tag messages for filtering:
amq send --to codex --labels "bug,urgent" --body "Critical issue"
Context provides structured metadata:
amq send --to codex --kind review_request \
--context '{"paths": ["internal/cli/send.go"], "focus": "error handling"}' \
--body "Please review"
[a-z0-9_-]+p2p/<agentA>__<agentB> (lexicographic)Read these when you need deeper context:
references/coop-mode.md — Read when setting up or debugging co-op workflows between agentsreferences/message-format.md — Read when you need the full frontmatter schema (all fields, types, defaults)