File-based message queue for agent-to-agent coordination.
\nAMQ 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.
\nRequires amq binary in PATH. Install:
curl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash\nAMQ primarily uses AM_ROOT (which mailbox tree) and AM_ME (which agent).\nPinned terminals also carry AM_BASE_ROOT plus an independent AM_SESSION\nidentity; sessionless pins use the exact root as AM_BASE_ROOT and an empty\nAM_SESSION. Getting these wrong means messages go to the wrong place or\nsilently 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\namq send --me claude --to codex ... # wrong — --me overrides the env\n./amq send ... # wrong — use amq from PATH\nThe reason: coop exec sets AM_ROOT, AM_ME, AM_BASE_ROOT, and\nAM_SESSION precisely for the session. Passing --me overrides the identity;\nfor read-side sibling access, use --session <name> instead of overriding the\nraw 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\namq_context=\"$(amq env --session auth --me claude --export)\" && eval \"$amq_context\" # pin one session\n\n# Or use an isolated subshell without polluting the parent shell:\n(\n amq_context=\"$(amq env --me claude)\" &&\n eval \"$amq_context\" &&\n amq send --to codex --body \"hello\"\n)\nWhy not hardcode? The root path depends on project and explicit configuration,\nthen context-sensitive implicit fallbacks. Hardcoding skips this and breaks\nwhen the project moves or config changes.\nEvery shell-mode amq env invocation replaces the complete context. It emits\nAM_SESSION unconditionally (empty for a sessionless root), exports\nAM_BASE_ROOT as the authorized parent for named sessions or the exact root for\na sessionless context.\n--export additionally prints a stderr pin note. Treat the evaluated output as\none terminal, one session.
Global fallback: Orchestrator-spawned agents often start outside an\nAMQ-enabled repo where no project .amqrc or repo-local .agent-mail exists.\nSet AMQ_GLOBAL_ROOT or ~/.amqrc so amq env and amq doctor still resolve\nthe correct queue. AMQ_GLOBAL_ROOT is explicit authority and therefore\nprecedes repo-local auto-detection. The implicit home config is ineligible\ninside a Git worktree or bare repository.\nA Git worktree or bare repository with no eligible root refuses implicit\n~/.amqrc fallback because it can silently select another project's mailbox.\nParticipating commands keep that refusal. coop exec honors root precedence,\nthen bootstraps a worktree-local queue at the Git top when no eligible root\nexists; coop exec --no-init refuses. coop init explicitly targets that local\nGit top. Bare repositories require a worktree or an explicit --root.
Session pitfall: Selector-free coop exec uses the declared default_session from .amq/launch.json, or collab (i.e., .agent-mail/collab). Outside coop exec, the base root is .agent-mail (no session suffix). These are different mailbox trees — don't mix them up.
| Context | \nCommand | \nAM_ROOT resolves to | \n
|---|---|---|
Outside coop exec | \namq env --me claude | \nresolved base root from project .amqrc, AMQ_GLOBAL_ROOT, or an eligible implicit fallback | \n
Git worktree or bare repository, no project .amqrc | \namq env --me claude | \nAMQ_GLOBAL_ROOT when set, otherwise repo-local detected .agent-mail | \n
| Git worktree or bare repository, no eligible root | \namq env --session auth --me claude | \nrefuses implicit ~/.amqrc; requires a local or explicit root | \n
| Git worktree, no eligible root | \namq coop exec claude | \nbootstraps <git-top>/.agent-mail/collab; never consults ~/.amqrc | \n
| Git worktree, no eligible root | \namq coop exec --session auth claude | \nbootstraps <git-top>/.agent-mail/auth | \n
| Git worktree, no eligible root | \namq coop exec --no-init claude | \nrefuses and names amq coop init as the remedy | \n
| Bare repository, no eligible root | \namq coop exec claude | \nrefuses; use a worktree or explicit --root | \n
Outside coop exec, isolated session | \namq env --session auth --me claude | \n<resolved-base-root>/auth | \n
Inside coop exec (no flags) | \nautomatic | \n.agent-mail/collab (default session) | \n
Inside coop exec --session X | \nautomatic | \n.agent-mail/X | \n
Canonical root precedence is:
\nexplicit --root > AM_ROOT > project-local .amqrc > AMQ_GLOBAL_ROOT > implicit fallbacks\nInside a Git worktree or bare repository, the remaining eligible fallback is repo-local detected\n.agent-mail; outside Git, ~/.amqrc precedes detected .agent-mail.
An initialized cwd-local queue is also a routing safety signal. If an active\npin points to another root, implicit participating commands refuse instead of\nsilently following that pin. Repin to the cwd-local queue, route deliberately\nwith --session/--project, or pass an explicit --root to confirm the\nactive queue; ordinary pin checks still apply.
A relative project root such as {\"root\":\".agent-mail\"} and auto-detected\nroots are intentionally per-worktree. Two terminals in different git\nworktrees can therefore use the same session name while reading different\nmailboxes. If a delivery receipt times out, run amq doctor --ops; it can warn\nwhen a peer has fresher presence in the same session under another worktree.
To share one mailbox across worktrees, use the same absolute root in each\nworktree's machine-local .amqrc, or remove the project-relative .amqrc and\nset AMQ_GLOBAL_ROOT to one absolute base. Keep the relative default when\nper-worktree isolation is intended. A Git worktree with neither local\nconfiguration nor a local queue fails closed instead of inheriting\n~/.amqrc; this prevents accidental cross-project delivery. A nested or\nlinked worktree under a parent that already has .amqrc is the same\nfail-closed ceiling: it uses its own config or refuses, and does not adopt\nthe parent live queue.
Before diving in, match the task to the right workflow — this avoids wasted effort:
\n| Your task | \nWhat to do | \n
|---|---|
| \"spec\", \"design with\", \"collaborative spec\" | \nUse /amq-spec instead — it has structured phase-by-phase guidance for parallel-research workflows. | \n
| Send a message, review request, question | \nUse amq send (see Messaging below) | \n
Buzz / ACP / amq-acp | \nCompanion amq-acp queues to AMQ_ACP_TO; pool workers must not drain. Chat must not pass --root, recipients, or argv. [Context] is not routing. See cmd/amq-acp/README.md. | \n
Two-host / Grok computer / amq-bridge | \nCompanion amq-bridge, never a foreign --root. See Two-host fleets below. | \n
| Swarm / agent teams | \nRead references/swarm-mode.md, then use amq swarm | \n
Received message with labels workflow:spec | \nFollow the spec skill protocol: do independent research first, then engage on the spec/<topic> thread — don't skip straight to implementation. | \n
The repository README Getting started\nis the canonical human onboarding path. The commands below keep the agent\nworkflow self-contained.
\n# Interactive one-time project setup\namq setup\n\n# Non-interactive setup: re-pass the same explicit inputs on preview and apply\nsetup_args=(--agents claude,codex --default-session collab --launcher-preference commands)\nsetup_preview=\"$(amq setup --preview --json \"${setup_args[@]}\")\"\nsetup_digest=\"$(printf '%s\\n' \"$setup_preview\" | jq -r '.preview.digest')\"\namq setup --apply \"$setup_digest\" \"${setup_args[@]}\"\n\n# Daily entry: reconcile the declared session (never creates an unknown name)\namq launch\namq session create feature-x # once, before the first named-session launch\namq launch --session feature-x\namq session resume feature-x\nsetup --preview performs zero writes. On a fresh non-interactive setup,\n--agents, --default-session, and --launcher-preference are required.\n--apply recomputes the preview and exits 6 without writes unless the\napproved sha256:<hex> digest matches. It is mutually exclusive with -y;\n--preview is also mutually exclusive with -y.
For Cursor, setup uses the current agent command when it is on PATH; if it\nis absent, the preview explains that setup is falling back to legacy\ncursor-agent.
Grok Build is supported by the managed launch adapter. It mints an exact\n--session-id from the AMQ launch nonce and resumes only with the stored\n--resume <UUID>; --continue, --always-approve, and --yolo are rejected\nfrom committed launch arguments. Grok tool policy uses its canonical\n--tools and --disallowed-tools flags; do not translate those values through\nClaude's --allowedTools grammar.
Put provider flags in the committed .amq/launch.json command arrays. The\nlauncher validates them and includes them in the semantic trust digest. The\nfirst semantic plan, and each plan change, needs an interactive trust\nconfirmation stored outside the worktree. Non-interactive or --json calls\nexit 6 until that digest is trusted. An unknown session resume name exits\n3 and writes nothing. Registered launchers are commands, tmux, cmux,\nand ghostty. --launcher auto walks the local preference; an explicit\n--launcher <name> wins. Inside cmux (CMUX_SURFACE_ID) is preferred over\ninside Ghostty (TERM_PROGRAM=ghostty). Setup lists cmux and Ghostty as\navailable only when Detect ping succeeds, not from LookPath alone. The\ncommands backend prints complete coop exec commands and exits 6 because\nrunning them is the remaining operator action. Paste the emitted lines exactly,\none per terminal; do not reconstruct them from generic coop exec examples.\nManaged tmux, cmux, and ghostty backends run the plan in-app instead.
Without --session or --root, coop exec uses the declared default_session from .amq/launch.json, or collab when none is declared. Creating a missing session or root from coop exec is deprecated and prints warning: creating a missing session or root from coop exec is deprecated; use 'amq session create <name>' or 'amq init --root'. The next major release makes this exit 3.
Direct coop exec names the provider session by default as\n<session>/<handle>, or as <handle> for a sessionless root. Claude and Pi\nget --name; Codex and Cursor agent get a best-effort TUI rename after the\nnew session store is verified. Codex resumes by name, for example codex resume session1/codex. Cursor agent resumes through its picker only; resume-by-name\nis unproven. Existing names and --resume, -r, --continue, or -c flags\nare preserved, including codex resume and agent --resume. Disable naming\nwith --named=false, AMQ_COOP_NAMED=0, or\n\"named\": false in .amq/launch.json. Managed launches keep naming disabled\nuntil their provider-name contract is available; explicit --named remains\nrefused there.
Add --no-gitignore when coop exec should auto-initialize the project without changing .gitignore.
Direct coop exec is legacy low-level plumbing. When an operator deliberately\nuses it, provider flags follow --; dangerous bypass flags belong only on this\noperator-controlled path and are rejected from committed launch arguments:
amq coop exec claude -- --dangerously-skip-permissions\namq coop exec codex -- --dangerously-bypass-approvals-and-sandbox\namq coop exec grok\nStandalone wake keeps urgent interrupt notices and the bell without injecting\nCtrl+C by default:
\namq wake --me claude --interrupt-cmd none &\nSwarm bridge events are hardcoded priority=normal plus label swarm, so do\nnot bind that combination to Ctrl+C. Use ordinary non-destructive wake:
amq wake --me codex --interrupt-cmd none &\n--interrupt-cmd ctrl-c sends a real SIGINT to the foreground process group\nand can interrupt or crash the agent. Use it only with a separate,\noperator-controlled label/priority when process-level interruption is\nintentional; the interrupt label alone never enables Ctrl+C.
To show the current AMQ session in your Claude Code status bar, add this snippet to your statusline script (e.g., ~/.claude/statusline.sh):
# AMQ session segment — try CLI first, fall back to env vars for older amq versions\namq_session=\"\"\nif _amq_out=$(amq env --session-name 2>/dev/null) && [ -n \"$_amq_out\" ]; then\n amq_session=\"$_amq_out\"\nelif [ -n \"$AM_ROOT\" ] && [ -n \"$AM_BASE_ROOT\" ] && [ \"$AM_ROOT\" != \"$AM_BASE_ROOT\" ]; then\n amq_session=$(basename \"$AM_ROOT\")\nfi\nif [ -n \"$amq_session\" ]; then\n output+=$(printf \" | \\033[33mamq:%s\\033[0m\" \"$amq_session\")\nfi\namq env --session-name (v0.27+) prints the session name and exits 0 (empty when not in a session). The env-var fallback covers older versions. amq env --json also includes session_name.
To also set the terminal tab title (works in Ghostty, iTerm2, Terminal.app):
\n# Set tab title to \"repo | amq:session\" — re-asserts on each statusline refresh.\n# Manual titles (e.g. Ghostty's prompt_tab_title) take priority and won't be overwritten.\ntab_title=\"$repo_name\"\n[ -n \"$amq_session\" ] && tab_title+=\" | amq:${amq_session}\"\nprintf '\\033]0;%s\\007' \"$tab_title\" > /dev/tty 2>/dev/null\n# Global fallback for orchestrator-spawned agents\nexport AMQ_GLOBAL_ROOT=\"$HOME/.agent-mail\"\n\n# Symphony hooks\namq integration symphony init --me codex\namq integration symphony emit --event after_run --me codex\n\n# Cline Kanban bridge\namq integration kanban bridge --me codex\namq integration kanban bridge --me codex --workspace-id my-workspace\n\n# Runtime diagnostics\namq doctor --ops\namq doctor --ops --json\namq doctor --root <exact-root> --ops\namq wake check --me <agent>\namq wake check --me <agent> --json\n\n# Base-config-only session repair outside the current pin\namq doctor --root <session-root> --base-root <base-root> \\\n --ignore-session-pin --fix-mailboxes\nTreat AMQ's process exit code as the stable machine contract:
\n| Code | \nMeaning | \n
|---|---|
0 | \nSuccess. The command completed normally. | \n
1 | \nGeneral error. The failure has no more specific exit-code classification. | \n
2 | \nUsage error. Arguments, flags, or command input are invalid. | \n
3 | \nNot found. A requested resource such as a mailbox, message, session, agent, or configuration does not exist. | \n
4 | \nTimeout. A watch, monitor, receipt wait, or delivery wait reached its deadline. | \n
5 | \nContext mismatch. A syntactically valid route was refused, including a pin conflict or an ineligible implicit root inside Git. | \n
6 | \nAction required. The command cannot proceed without an operator action (untrusted launch plan, unknown backend inspect, stale conversation token, blocked rebind, or emitted coop exec commands still to run). | \n
Do not parse stderr prose as a stable discriminator. --json preserves the\nsame process exit codes. A read-only list on a mismatched session pin warns\nand continues; commands that consume or mutate mailbox state fail with code\n5.
When a command reports per-agent outcomes, whole-command failures that precede\nany per-agent work keep codes 2, 5, and 3 and preempt mixed results. Once\nper-agent work begins, the process exit code is the highest-precedence per-agent\noutcome: 6 over 4 over 1 over 0. Expected dispositions (disabled,\nunsupported, and policy-consistent fresh) contribute 0. Launch Apply and\nlifecycle JSON also carry a typed mutation disposition (not_applied,\ncommitted, or uncertain) for the backend binding; that field is not a\nprocess exit code.
AMQ records delivery outcomes in consumer-local receipt files. The main stages are:
\ndrained — a consumer successfully ingested the messagedlq — the message was moved to the dead letter queue during ingestUse these when you need confirmation rather than just fire-and-forget messaging:
\n# Block on delivery for a single-recipient send\namq send --to codex --body \"please review\" --wait-for drained --wait-timeout 60s\n\n# Query receipt history later\namq receipts list --me codex --msg-id <msg_id>\namq receipts wait --me codex --msg-id <msg_id> --stage drained --timeout 60s\namq read, amq drain, and amq monitor all apply the same strict header validation. Messages in inbox/new that are corrupt or have malformed headers are moved to DLQ and produce a dlq receipt.
DLQ retries use four durable states: ready, pending, delivered, and\nindeterminate. A successful retry retains a terminal audit in dlq/cur until\npurge. delivered is idempotent and reports already_delivered plus\naudit_finalized; --force cannot redeliver it. A pending or legacy\nindeterminate envelope without a visible inbox destination refuses retry,\nincluding with --force; that flag bypasses only the maximum retry count.\nBulk JSON separates retried, already_delivered, and skipped, and its\ncount includes only newly retried messages.
amq who and amq doctor --ops report notifier_live only when the wake-lock\ninspector verifies a live amq wake process identity. That proves prompt\nnotification, not message consumption. recent_activity means only that\nlast_seen is fresh. Use drain or monitor when consumption is required;\nrun long-lived wake/monitor commands under launchd, systemd, or another\nsupervisor rather than treating AMQ itself as a daemon.
Before replacing a wake, run amq wake check --me <agent> --json. It is\nread-only and reports the running/current image path and version plus an exact\nnext_action. An automated agent may act only when\nrestart_capability=agent_safe. For operator_only, leave the live wake\nrunning and hand off to its owning terminal or supervisor. For unavailable,\npreserve the state and diagnose it. Never kill a live raw wake from a non-TTY\nprocess, and never accept an attention-only fallback as a replacement for\nfull-strength input delivery. When the recorded image or restart stage lives\nunder a directory that no longer exists, the check reports\nreason_code=binary_dir_gone and names amq doctor --ops --fix-wake-locks\ninstead of a raw ENOENT.
Current resume-eligible coop exec wakes automatically observe their stable\nAMQ launch symlink and adopt a strictly newer semantic version at a fully\nquiescent boundary, preserving PID, terminal ownership, and unread messages.\nUse wake check --json --json-schema=2 to inspect self_upgrade; a failed\nupgrade candidate is attempted at most once per candidate within one wake\ngeneration, bounded to the 8 most recent distinct candidates, and a new\ngeneration resets that refusal memory. --no-self-upgrade and AMQ_WAKE_NO_SELF_UPGRADE=1 disable\nthis only for the launched wake. Ownerless, keepalive, repair, destructive\ninterrupt, arbitrary-inject, and pinned-path wakes remain manual.
Those consuming commands, watch, and all DLQ commands refuse a raw\ntarget that conflicts with a complete AM_BASE_ROOT/AM_SESSION pin before\ntouching mailbox state. send and reply apply the same check to their source\ncontext. Use --session <name> for deliberate sibling access. The raw-root\nescape hatch, --ignore-session-pin, requires a non-empty explicit --root;\nit never blesses an inherited AM_ROOT. list warns and remains available for\nnon-destructive inspection. With no session/tree evidence, scripts and CI\nremain fail-open. A missing mailbox is an error, not an empty inbox. Empty\ndrain and list --new results may print a stderr note when the same handle\nhas pending messages in a sibling session; follow the exact amq list --session <name> --me <handle> --new command in that note.\nThis is an operational safety check, not an authorization boundary; a local\nprocess can deliberately repin or override it.
For doctor, --root selects the exact target but does not waive the active\npin. Read-only inspection continues and reports a mismatch warning.\n--fix-mailboxes and --ops --fix-wake-locks require a matching pin unless an explicit non-empty\n--root is paired with --ignore-session-pin. --base-root requires\n--root, supplies retained config authority for the target or one direct\nchild, and never waives the pin.
By default, the root is .agent-mail (from .amqrc or auto-detect). Use --session to create isolated subdirectories:
.agent-mail/ ← default root (configurable in `.amqrc`)\n.agent-mail/auth/ ← isolated session (via --session auth)\n.agent-mail/api/ ← isolated session (via --session api)\namq coop exec claude → AM_ROOT=.agent-mail/collab (default session)amq coop exec --session auth claude → AM_ROOT=.agent-mail/authThe main env vars are AM_ROOT (where) + AM_ME (who). coop exec also sets\nAM_BASE_ROOT for cross-session resolution and AM_SESSION as the independent\nsession identity used by consuming-command guards. The CLI enforces correct\nrouting — run bare commands for the current session or use --session for a\nnamed sibling.\nDefault .agent-mail/<session> layouts are recognized even without .amqrc; custom root names still need config or explicit flags/env.
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.
Add project and peers to your .amqrc:
{\n \"root\": \".agent-mail\",\n \"project\": \"my-project\",\n \"peers\": {\n \"infra-lib\": \"/Users/me/projects/infra-lib/.agent-mail\"\n }\n}\nBoth projects must register each other as peers for round-trip messaging.
\nUse --project/--session to route, not a raw --root. A direct --root selects which tree to operate on; it carries no sender-origin metadata, so the recipient can't reply (a naive reply loops back into their own tree). amq send therefore refuses an explicit --root that crosses into a different base tree than your active session (AM_ROOT/AM_BASE_ROOT) when no --project/--session/--from-session is given. To message another project replyably, register the peer and use --project (or inline @project). If a send is genuinely local, set the target as your AM_ROOT instead of passing --root.
# Flag syntax\namq send --to codex --project infra-lib --body \"hello from here\"\n\n# Inline syntax (terser)\namq send --to codex@infra-lib:collab --body \"inline syntax\"\n\n# Same session name as source (default when --session omitted)\namq send --to codex --project infra-lib --body \"delivers to same session\"\nWhen 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\np2p/claude__codexp2p/projA:collab:claude__projB:collab:codexdecision/release-v0.24For full details, see references/cross-project.md.
\nWhen you receive a message where from matches your own handle (e.g., from: \"claude\" and you are claude), check from_project and reply_project. If either is present and names a different project, this is NOT an echo — it is a legitimate cross-project message from a different agent instance with the same handle. Process it normally.
After sending a cross-project message (via --project), your AM_ROOT still points to YOUR project. To send to your own partner (same project), use plain amq send --to codex — do NOT use --project. The --project flag is ONLY for sending to agents in OTHER projects.
A different machine is a different AMQ host, not a --project and not a\nforeign --root. Each host has its own handles; claude on G is not claude\non the Mac. Cross-host mail is companion amq-bridge only.
<host>/<agent>.amq-bridge apply-file (operator-moved drop file, no\npublic locker). Replies keep the inbound opaque thread id.scripts/amq-bridge-bot-enqueue.sh with argv exactly\n--dest-alias host/agent; it reads AMQ_BRIDGE_ENQUEUE_CONFIG. Prompt text\nmust not pass --root, --rendezvous, --me, or --spool.See amq-bridge.
\nDecentralized decision protocol using existing AMQ primitives (no new CLI commands).
\ndecision/<topic>decision for all messagesdecision:proposal, decision:objection, decision:support, decision:final; plus project:<name> for cross-project decisions{\"proposal_id\": \"...\", \"question\": \"...\", \"options\": [...], \"required_projects\": [...], \"deadline\": \"...\"}Process: Propose → Review/Object → Resolve objections → Close when all required projects responded and no unresolved blocking objections.
\namq send --to codex --project infra-lib --kind decision \\\n --labels \"decision:proposal,project:my-project,project:infra-lib\" \\\n --thread \"decision/api-v2\" \\\n --context '{\"proposal_id\":\"api-v2\",\"question\":\"Adopt new API?\",\"required_projects\":[\"my-project\",\"infra-lib\"]}' \\\n --body \"Proposal: migrate to API v2. All tests green.\"\nUsers refer to sessions using many words: \"session\", \"stream\", \"squad\", \"team\", \"workspace\", \"channel\", or just a bare name. When the user mentions sending to or talking to an agent in a named context (e.g., \"ask codex on stream1\", \"send to the auth team\", \"talk to codex in squad-api\"), you must discover sessions before routing.
\nImportant: Do not confuse sessions with projects. \"Project\" in AMQ means a different repo/codebase (cross-project routing via --project). Sessions are isolated mailbox trees within the same project (via --session). If the user says \"the infra project\", that likely means --project infra, not --session infra.
# Step 1: Discover active sessions and agents\namq who --json\n# Returns: [{\"name\":\"collab\",\"agents\":[...]},{\"name\":\"stream1\",\"agents\":[...]},{\"name\":\"auth\",\"agents\":[...]}]\n\n# Step 2: Match the user's name against session names in the output, then send\namq send --to codex --session stream1 --body \"Message for stream1\"\nRecognition patterns — any of these mean \"route to a specific session\":
\nNote: The agent@name inline syntax (e.g., codex@infra) is for cross-project routing, not cross-session. For same-project session routing, always use --session <name> explicitly.
Rules:
\namq who --json first to check if it matches a known session name--session <name> on the send command$AM_ROOT basename), use --session <name>amq who --json output, tell the user (it may need amq session create <name>)--project instead — see Cross-Project Routing sectionamq send --to codex --body \"Message\" # Send (uses AM_ROOT/AM_ME from env)\namq drain --include-body # Receive (one-shot, silent when empty)\namq drain --session auth --include-body # Deliberate sibling-session receive\namq reply --id <msg_id> --body \"Response\" # Reply in thread\namq watch --timeout 60s # Block until message arrives\namq list --new # Peek without side effects\namq send --to grok --body \"hello\" # Grok is a normal peer handle, like codex or claude\namq send --to codex --subject \"Review\" --kind review_request --body @file.md\namq send --to codex --priority urgent --kind question --body \"Blocked on API\"\namq send --to codex --labels \"bug,parser\" --context '{\"paths\": [\"src/\"]}' --body \"Found issue\"\necho \"evidence: tests green\" | amq send --to codex --subject \"done\" --body - # - reads stdin\nBody is fail-closed. --body - (or --body @-, or omitting --body) reads stdin; a literal string or @file is used as-is. A send whose resolved body is empty/whitespace is rejected with a usage error instead of delivering a blank message — so --body - with nothing piped fails loudly rather than shipping an empty body. Pass --allow-empty only when you truly want a blank body (subject carries everything).
Unrouted self-addressing is fail-closed. When --to resolves to your own handle and no --project, --session, or --from-session routing dimension is present, amq send refuses the ambiguous same-root send. Use routing to reach another instance of the same handle. Pass --allow-self only to confirm an intentional same-root self-send; it does not bypass cross-tree or session-pin guards.
Send file paths, not file contents. When attaching source code, configs, or large text for review, send the file path in the message body, not the contents inline. The receiver can open the file with their local tools. If the receiver cannot access that worktree, send a short diff instead of the full source.
\namq list --new --priority urgent\namq list --new --from codex --kind review_request\namq list --new --label bug\nAlmost all coordination is agent-to-agent. Occasionally the next required actor is a human: an approval, a manual test, a deploy only a person can run, or sign-off that a goal is complete. AMQ has no separate \"gate\" feature. You represent this structurally: address a message to the human's mailbox instead of describing the wait in prose to another agent.
\nThe single invariant AMQ relies on here is recipient-as-next-actor: a message addressed to the human handle means a human is who must act next. Everything else below (the gate/<topic> thread name and the APPROVAL: / DONE: subject prefixes) is a naming convention that downstream tools like amq-noc watch for. AMQ routing and message classification do not special-case thread names or subject text; those are plain strings, useful only because humans and tooling agree to read them. They are conventions, not core AMQ semantics.
userBy convention the human/operator mailbox is user. AMQ reserves this handle for validation in configured projects, so --to user is accepted wherever the project has a configured agent list. New co-op projects include user in the default agent set. For explicit amq init --agents ... projects or older roots, initialize the mailbox layout before relying on human drain/receipt/DLQ ergonomics:
# Seed the human mailbox alongside the agents (one-time, per project)\namq init --root .agent-mail --agents claude,codex,user\n# or, for a coop project:\namq coop init --agents claude,codex,user\nThroughout this section, user means \"the conventional human handle.\" In configured projects it is warning-free for strict handle validation; in older or explicitly seeded roots, make sure the agents/user/ mailbox exists before expecting a human to drain and reply from it.
Use a stable gate/<topic> thread so a gate and its resolution stay together:
# Approval / choice / manual test a human must perform\namq send --to user --thread gate/<topic> --kind question \\\n --subject \"APPROVAL: <decision>\" \\\n --body \"<what you need a human to approve or run, and why>\"\n\n# Human closeout of a completed goal (sign-off that the goal is done)\namq send --to user --thread gate/<topic> --kind decision \\\n --subject \"DONE: <goal>\" \\\n --body \"<what was completed; what the human should confirm or close>\"\nThe human answers on the same thread from their own terminal or client, e.g. amq send --me user --to <agent> --thread gate/<topic> --kind answer --subject \"APPROVED: <decision>\" --body \"<approval / answer text>\" (use DENIED: or ANSWER: for a rejection or a plain answer). Reusing the gate/<topic> thread is what lets a watcher pair the answer with the open gate and clear it.
Keep ordinary coordination agent-to-agent. Do not send to user for:
status on a normal threadreview_request / review_responseIf the escalation owner is a lead/CTO agent, they decide whether to escalate, and that decision is agent-to-agent. But once a human action is actually required, it still becomes a to:user gate so tooling can observe it.
Prose like operator-held, pending operator, or manual approval inside an agent-to-agent message is not a gate. It is body text a human or tool has to guess at. If a human must act, address the human.
to:user gate records that a human is the next actor; it does not grant permission or prove a human approved anything. Do not treat it as an access-control boundary.user is a deliberate act (--session / --project), never the default. Gate-clearing is a consumer/orchestrator convention unless AMQ later adds explicit gate state.| Priority | \nAction | \n
|---|---|
urgent | \nInterrupt current work, respond now | \n
normal | \nAdd to TODOs, respond after current task | \n
low | \nBatch for session end | \n
| Kind | \nReply Kind | \nDefault Priority | \n
|---|---|---|
review_request | \nreview_response | \nnormal | \n
question | \nanswer | \nnormal | \n
decision | \n— | \nnormal | \n
todo | \n— | \nnormal | \n
status | \n— | \nlow | \n
brainstorm | \n— | \nnormal | \n
For detailed protocols, read the reference file FIRST, then follow its instructions:
\n