amq-cli

AMQ CLI Skill

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

AMQ manages the conversation, not the task plan. Use it for messaging, routing, replies, and adapter-emitted lifecycle events; keep work decomposition and execution in the orchestrator above it.

Prerequisites

Requires amq binary in PATH. Install:

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

Environment Rules

AMQ primarily uses AM_ROOT (which mailbox tree) and AM_ME (which agent). Pinned terminals also carry AM_BASE_ROOT plus an independent AM_SESSION identity; sessionless pins use the exact root as AM_BASE_ROOT and an empty AM_SESSION. Getting these wrong means messages go to the wrong place or silently disappear, so let the CLI handle them rather than guessing.

Inside coop exec — everything is pre-configured. Just run bare commands:

amq send --to codex --body "hello"     # correct
amq send --me claude --to codex ...    # wrong — --me overrides the env
./amq send ...                         # wrong — use amq from PATH

The reason: coop exec sets AM_ROOT, AM_ME, AM_BASE_ROOT, and AM_SESSION precisely for the session. Passing --me overrides the identity; for read-side sibling access, use --session <name> instead of overriding the raw root.

Outside coop exec — resolve the root from config, don't hardcode it:

amq_context="$(amq env --me claude)" && eval "$amq_context"  # reads .amqrc chain, replaces the full context
amq_context="$(amq env --session auth --me claude --export)" && eval "$amq_context"  # pin one session

# Or use an isolated subshell without polluting the parent shell:
(
  amq_context="$(amq env --me claude)" &&
  eval "$amq_context" &&
  amq send --to codex --body "hello"
)

Why not hardcode? The root path depends on project and explicit configuration, then context-sensitive implicit fallbacks. Hardcoding skips this and breaks when the project moves or config changes. Every shell-mode amq env invocation replaces the complete context. It emits AM_SESSION unconditionally (empty for a sessionless root), exports AM_BASE_ROOT as the authorized parent for named sessions or the exact root for a sessionless context. --export additionally prints a stderr pin note. Treat the evaluated output as one terminal, one session.