amq-cli

AMQ CLI

Use the amq CLI for all queue operations. Never edit Maildir files directly. AMQ transports coordination; the caller or orchestrator still owns task planning, worktrees, approvals, and delivery.

Start in the correct context

Inside coop exec, use the environment as provided and run bare amq commands. Do not override --me or reconstruct the root. Outside it, resolve and export the complete context before reading or sending:

amq_context="$(amq env --me "<handle>" --export)" && eval "$amq_context" &&
  amq drain --include-body

For a named session, add --session <name> to amq env. Treat the evaluated context as one terminal bound to one session. Use --session or --project for deliberate routing; do not point a participating command at another queue with a raw --root.

Receive under a live wake

If session-start context says wake=live(...), or amq wake check --me <handle> --json reports live_wake: true with an injection mode other than none, the wake delivers a doorbell for you. Run amq drain --include-body when it fires, then act on the messages.

Do not run amq watch, amq monitor, sleep-poll, or start another inbox watcher under that live wake. A blocking wait holds your turn while the doorbell queues behind it. When your work is done, finish the turn; do not keep a tool running or send idle check-ins just to wait for mail.

Without an injecting wake, use the receive methods in the operations guide. A notify-only wake (--inject-mode none) paired with a supervisor monitor service is a separate supported setup.

Route the task

Need	Read or run
Send, reply, drain, inspect receipts, or diagnose	Use the operations guide.
Two-agent research and design	Use the amq-spec skill.
Co-op roles and phased collaboration	Read co-op mode.
Claude Code Agent Teams	Read swarm mode.
Cross-project delivery or decision threads	Read cross-project routing.
Grok Bot on a registered Mac	Read registered-machine execution.
Symphony or Kanban adapters	Read integrations.
Message schema details	Read message format.
Multi-round background review	Read review loop.
Attach to a running harness session	Read the amq-remote reference.

Use amq <command> --help for current flags. The repository README is the canonical setup path.

Remote

amq-remote is a companion binary, not an amq subcommand. It attaches to a harness session that is already running. Targets are declared in <AM_ROOT>/extensions/remote/manifest.json (claude, codex, amit, or fake). up supervises the endpoint; submit, status, wait, and cancel talk to it; share mints the session body key. A manifest relay object shares a target with its owner over a Buzz relay. DM commands require the pinned native_session_id and run only while that session is attached; Desktop presence reports the attachment status and honors the pin when one is set. doctor lists each failing boundary under failing and exits 6 while any remains. Flags and exit codes are in the amq-remote reference. The design is the remote-control ADR. Pinned seams are the compatibility manifest.

Safety and delivery rules

• A wake notification is attention, not consumption proof. Use receipts or --wait-for drained when delivery proof matters.
• Preserve the existing thread when replying. Drain again after a doorbell; the newest complete message body is authoritative.
• Cleanup is explicit through amq cleanup. Do not add automatic deletion.
• Before any wake mutation, run amq wake check --me "<handle>" --json. Act only when restart_capability=agent_safe; otherwise preserve state and report the required operator action.
• Keep cross-host payloads outside privileged inboxes until the configured bridge has authenticated and applied them. Never copy or remote-drain a foreign Maildir as a substitute for routing.
• Do not translate native Windows injection into Unix wake or coop exec. Read the platform section in the operations guide when Windows is involved.
• Dangerous provider bypass flags belong only on an operator-controlled direct coop exec command. Do not place them in committed launch configuration.

The full command catalog, environment precedence, setup flow, platform notes, operator gates, and examples are in the operations guide.