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

Context	Command	AM_ROOT resolves to
Outside `coop exec`	`amq env --me claude`	base root from `.amqrc` (e.g. `.agent-mail`)
Outside `coop exec`, isolated session	`amq env --session auth --me claude`	`.agent-mail/auth`
Inside `coop exec` (no flags)	automatic	`.agent-mail/collab` (default session)
Inside `coop exec --session X`	automatic	`.agent-mail/X`

Task Routing — READ THIS FIRST

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

Your task	What to do	DO NOT
"spec", "design with", "collaborative spec"	Use the `/spec` command instead. It provides structured phase-by-phase guidance.	Do NOT handle spec tasks from this skill.
Send a message, review request, question	Use `amq send` (see Messaging below)	—
Swarm / agent teams	Read references/swarm-mode.md, then use `amq swarm`	—
Received message with labels `workflow:spec`	Follow the spec skill protocol: do independent research first, then engage on the `spec/<topic>` thread.	Do NOT skip straight to implementation.

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

Priority	Action
`urgent`	Interrupt current work, respond now
`normal`	Add to TODOs, respond after current task
`low`	Batch for session end

Message Kinds

Kind	Reply Kind	Default Priority
`review_request`	`review_response`	normal
`question`	`answer`	normal
`decision`	—	normal
`todo`	—	normal
`status`	—	low
`brainstorm`	—	low

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

amq-cli