AMQ CLI Skill

File-based message queue for agent-to-agent coordination.

Prerequisites

Requires amq binary in PATH. Install:

curl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash

Environment Rules (IMPORTANT)

When running inside coop exec, the environment is already configured:

• Always use amq from PATH — never ./amq, ../amq, or absolute paths
• Never override AM_ROOT or AM_ME — they are set by coop exec
• Never pass --root or --me flags — env vars handle routing
• Just run commands as-is: amq send --to codex --body "hello"

When running outside coop exec (e.g. new conversation, manual terminal):

• Use amq env to resolve the root — it reads .amqrc and returns the base root:

  eval "$(amq env --me claude)"          # sets AM_ME + AM_ROOT from .amqrc
  

• Or resolve and pin explicitly per command (never hardcode the root — read it from .amqrc):

  AM_ME=claude AM_ROOT=$(amq env --json | jq -r .root) amq send --to codex --body "hello"
  

• Do NOT append a session name (e.g. /collab) unless you intentionally want an isolated session. Outside coop exec, the base root from .amqrc is where agents live.
• Pitfall: coop exec defaults to --session collab (i.e. .agent-mail/collab). If you manually use .agent-mail/collab outside coop exec, messages go to a different mailbox tree than .agent-mail. Only use a session path if the target agent is also in that session.

Root Resolution Truth-Table

Task Routing — READ THIS FIRST

Before doing anything, match your task to the right workflow:

Quick Start

# One-time project setup
amq coop init

# Per-session (one command per terminal — defaults to --session collab)
amq coop exec claude -- --dangerously-skip-permissions  # Terminal 1
amq coop exec codex -- --dangerously-bypass-approvals-and-sandbox  # Terminal 2

Without --session or --root, coop exec defaults to --session collab.

Session Layout

By default, .amqrc points to a literal root (e.g., .agent-mail). Use --session to create isolated subdirectories:

.agent-mail/              ← default root (configured in .amqrc)
.agent-mail/auth/         ← isolated session (via --session auth)
.agent-mail/api/          ← isolated session (via --session api)

• amq coop exec claude → AM_ROOT=.agent-mail/collab (default session)
• amq coop exec --session auth claude → AM_ROOT=.agent-mail/auth

Only two env vars: AM_ROOT (where) + AM_ME (who). The CLI enforces correct routing — just run amq commands as-is.

Messaging

amq send --to codex --body "Message"              # Send (uses AM_ROOT/AM_ME from env)
amq drain --include-body                          # Receive (one-shot, silent when empty)
amq reply --id <msg_id> --body "Response"          # Reply in thread
amq watch --timeout 60s                           # Block until message arrives
amq list --new                                    # Peek without side effects

Send with metadata

amq send --to codex --subject "Review" --kind review_request --body @file.md
amq send --to codex --priority urgent --kind question --body "Blocked on API"
amq send --to codex --labels "bug,parser" --context '{"paths": ["src/"]}' --body "Found issue"

Filter

amq list --new --priority urgent
amq list --new --from codex --kind review_request
amq list --new --label bug

Priority Handling

Message Kinds

References

For detailed protocols, read the reference file FIRST, then follow its instructions:

• references/coop-mode.md — Co-op protocol: roles, phased flow, collaboration modes
• references/swarm-mode.md — Swarm mode: agent teams, bridge, task workflow
• references/message-format.md — Message format: frontmatter schema, field reference