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

Verify: amq --version

Quick Start

# One-time project setup
amq coop init

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

That’s it. coop exec auto-initializes if needed, sets AM_ROOT/AM_ME, starts wake notifications, and execs into the agent.

Messaging

amq send --to codex --body "Message"              # Send
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

Root and agent handle are auto-detected from .amqrc and AM_ME. Commands work from any subdirectory.

Isolated Sessions (Multiple Pairs)

amq coop exec --root .agent-mail/auth claude      # Pair A
amq coop exec --root .agent-mail/auth codex
amq coop exec --root .agent-mail/api claude       # Pair B
amq coop exec --root .agent-mail/api codex

Each --root has isolated inboxes. Messages stay within their root.

For Scripts/CI

When you can’t use exec (non-interactive environments):

amq coop init
eval "$(amq env --me claude)"    # Set env vars manually

Co-op Protocol

Core Rules

1. Initiator rule — reply to the initiator; ask the initiator for clarifications
2. Never branch — always work on same branch
3. Code phase = split — divide files/modules to avoid conflicts
4. Shared workspace — reference file paths, don’t paste code in messages

Priority Handling

Progress Updates

amq reply --id <msg_id> --kind status --body "Started, eta ~20m"
amq reply --id <msg_id> --kind answer --body "Summary: ..."

Commands Reference

Send

amq send --to codex --body "Quick message"
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" --body "Found issue"
amq send --to codex --context '{"paths": ["internal/cli/"]}' --body "Review these"

Filter

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

Reply

amq reply --id <msg_id> --body "LGTM"
amq reply --id <msg_id> --kind review_response --body "See comments..."

Dead Letter Queue

amq dlq list                                      # List failed messages
amq dlq retry --id <dlq_id>                       # Retry one
amq dlq retry --all                               # Retry all
amq dlq purge --older-than 24h --yes              # Clean old entries

Other

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 --yes            # Clean stale tmp
amq upgrade                                       # Self-update

Message Kinds

Swarm Mode: Agent Teams

Enable external agents to participate in Claude Code Agent Teams.

amq swarm list                                    # Discover teams
amq swarm join --team my-team --me codex          # Join team
amq swarm tasks --team my-team                    # View tasks
amq swarm claim --team my-team --task t1 --me codex  # Claim work
amq swarm complete --team my-team --task t1 --me codex  # Mark done
amq swarm bridge --team my-team --me codex        # Run task notification bridge

Communication is asymmetric: bridge delivers task notifications only. Claude Code teammates can amq send to external agents. External agents relay messages to the team leader’s inbox.

References

• references/coop-mode.md — Phased workflow, collaboration modes, detailed coordination patterns
• references/message-format.md — Frontmatter schema cheat sheet (fields, types, defaults)