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:
  bashCopy

  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):
  bashCopy

  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.

Cross-Project Routing

Send messages to agents in other projects via --project or inline @project:session syntax. Requires peer configuration in .amqrc.

When to use --session vs --project: --session = same project, different session. --project = different project. Change one dimension at a time.

Peer setup

Add project and peers to your .amqrc:

{
  "root": ".agent-mail",
  "project": "my-project",
  "peers": {
    "infra-lib": "/Users/me/projects/infra-lib/.agent-mail"
  }
}

Both projects must register each other as peers for round-trip messaging.

Sending cross-project

# Flag syntax
amq send --to codex --project infra-lib --body "hello from here"

# Inline syntax (terser)
amq send --to codex@infra-lib:collab --body "inline syntax"

# Same session name as source (default when --session omitted)
amq send --to codex --project infra-lib --body "delivers to same session"

Replies route automatically

When you receive a cross-project message, reply_project is set in the header. amq reply routes back automatically — no --project flag needed:

amq reply --id <msg_id> --body "got it"  # routes back via reply_project

Thread naming

• Same project P2P: p2p/claude__codex
• Cross-project P2P: p2p/projA:collab:claude__projB:collab:codex
• Topical (cross-project): use same thread ID across projects, e.g., decision/release-v0.24

For full details, see references/cross-project.md.

Decision Threads

Decentralized decision protocol using existing AMQ primitives (no new CLI commands).

• Thread: decision/<topic>
• Kind: decision for all messages
• Labels: decision:proposal, decision:objection, decision:support, decision:final; plus project:<name> for cross-project decisions
• Context on proposals: {"proposal_id": "...", "question": "...", "options": [...], "required_projects": [...], "deadline": "..."}

Process: Propose → Review/Object → Resolve objections → Close when all required projects responded and no unresolved blocking objections.

amq send --to codex --project infra-lib --kind decision \
  --labels "decision:proposal,project:my-project,project:infra-lib" \
  --thread "decision/api-v2" \
  --context '{"proposal_id":"api-v2","question":"Adopt new API?","required_projects":["my-project","infra-lib"]}' \
  --body "Proposal: migrate to API v2. All tests green."

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
• references/cross-project.md — Cross-project routing: peer config, addressing, decision threads