README
¶
Agent Message Queue (AMQ)
Messaging between coding agents.
AMQ lets two coding agents exchange messages through a shared directory. One agent asks for a review; the other reads the message and replies in the same thread. Messages are plain files, so the local queue needs no messaging server or database—and you do not have to relay each request yourself.
Try the queue in a fresh shell on macOS. This example uses two mailbox names; it does not start agents. Other installation methods →
brew install avivsinai/tap/amq
amq init --root .agent-mail/demo --agents alice,bob # Create two mailboxes for demo.
amq send --root .agent-mail/demo --me alice --to bob --body "Please review the parser."
amq drain --root .agent-mail/demo --me bob --include-body
- Keep the conversation together. Reply in threads, attach context, and route messages between sessions or projects.
- Know what happened to a message. Receipts distinguish a queued message from one the recipient drained.
- Bring your own agents. Use the CLI from agent tools or scripts; optional wake notifications prompt running agents to check their inboxes.
- Keep control of the workflow. AMQ handles messages. You and your orchestration tools own tasks, worktrees, permissions, and merges.
Getting started
This walkthrough connects Claude Code and Codex CLI on one machine.
Install both agent CLIs and put claude and codex on PATH first.
Use macOS or Linux; on Windows, use WSL with the Linux binary for this
terminal workflow. Native Windows has a verified subset of queue and adapter
support; see the platform matrix.
1. Install the binary
On macOS:
brew install avivsinai/tap/amq
Or on macOS/Linux, review and run the installer:
curl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash
The script installs to a user-local directory without sudo and checks the
release checksum before extraction. Confirm the install with amq --version.
See Installation for manual downloads and source builds.
2. Install Skill
Install the agent instructions so each agent knows how to use AMQ:
npx skills add avivsinai/agent-message-queue -g -y
Restart the agents after installing. Other skill installation methods are available if you do not use npm.
3. Set up the project
In the repository where the agents will work:
amq setup
Select the agents and launcher, then confirm the preview. Setup writes the project configuration and creates the default session and its mailboxes.
4. Start both agents
amq launch
The first launch asks you to trust the launch plan. With tmux, cmux, or
ghostty, AMQ starts the agents in that terminal app. With the commands
backend, it prints one command per agent and exits with code 6 (action
required). Paste each complete command into a separate terminal; do not
shorten or rebuild it.
Optional, for Claude Code: amq wake install-dialog-hook keeps the wake from
typing into an open AskUserQuestion, plan, or permission dialog.
Start both agents before sending the first message. Messages that arrive
before a recipient's wake starts remain unread but do not trigger that new
wake. The recipient can still get them with amq drain --include-body.
Control a session from Buzz
Inside a running Claude Code session, type /amq-remote; inside Codex, invoke
the skill as $amq-remote (Codex does not register / commands for skills).
The first
time, import that session's agent into Buzz Desktop; with the AMQ Remote
helper imported once on the machine, Desktop opens the Create agent dialog
instead. Each session has its own agent, pinned to it by the system prompt
line AMQ Remote session: <name>. DM that agent from the Buzz app or
Desktop, and the DM runs in that session.
/amq-remote off disconnects it. See amq-remote.
5. Exchange a message
Ask Claude to run this command through its shell tool:
amq send --to codex --subject "Hello" --body "Can you see this?"
Ask Codex to check its inbox if it has not already responded to the notification:
amq list --new
amq drain --include-body
list previews new messages. drain reads them, moves them out of the new
inbox, and writes receipts. The output includes the sender and message body.
To reply in the same thread, use the ID from that output:
amq reply --id "<message-id>" --body "Yes, I can see it."
The launched agents already have their identity and session set. You do not
need to repeat --me or --root inside those sessions.
How it works
Each agent has an inbox and an outbox under a local queue root. A message contains a JSON header and a Markdown body. AMQ writes and syncs a temporary file, then publishes it with a rename: a reader sees a complete message or no message, not a partly written body.
A session is a separate queue. Routing checks help prevent a shell pinned to one session from changing another by mistake. A wake notification asks an agent to check its inbox; it is not evidence that the agent read or completed the request. See routing and message tracing for those contracts.
Optional priority holds can delay
the first notification for routine mail while urgent mail skips the hold. Wake
live settings have a machine default
for this user (amq wake config --machine --hold-normal 5m) and per-agent
overrides; use amq wake config --me <handle> --hold-normal 5m to change a
running wake.
AMQ is for local agent coordination, not a distributed broker. The optional bridge companion exchanges messages between hosts; each host keeps control of its own queue.
Remote
The optional remote companion connects a running
session to its own Buzz agent. The default path is the session mailbox: a DM
arrives as an AMQ message from buzz, and the agent's reply is the answer.
--native and the relay are the other paths. It is a separate binary: amq
gains no socket. The Homebrew amq formula installs amq, amq-acp,
amq-remote, amq-owner-sign, and amq-bridge. Commands, flags, and exit codes are in that README. The design is
the remote-control ADR; pinned seams are
the compatibility manifest.
Documentation
| I want to… | Read |
|---|---|
| Install, update, or use another platform | Installation |
| Run agent pairs, isolate sessions, or supervise notifications | Co-op operations |
| Batch routine wake notifications by priority | Wake operations |
| Look up a command or flag | CLI reference |
| Diagnose delivery or wake problems | Wake operations · Trace |
| Attach to a running harness session | amq-remote |
| Build an integration or understand the design | Documentation index |
| Understand the trust model | Security |
Building on AMQ? Use the adapter contract, launch API, and extension metadata. amq-squad is a role-aware team launcher built on these primitives.
Contributing
See the contribution guide for development and review.
Contributor clones should install the git hooks
(./scripts/install-hooks.sh) so pushes run the static checks locally.
Use GitHub issues
for questions and bug reports. Follow the code of conduct
and report security issues through the security policy.
License
MIT.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
amq
command
|
|
|
amq-acp
command
Command amq-acp is an Agent Client Protocol (ACP) version 2 bridge for AMQ.
|
Command amq-acp is an Agent Client Protocol (ACP) version 2 bridge for AMQ. |
|
amq-bridge
command
|
|
|
amq-keepalive
command
|
|
|
amq-owner-sign
command
Command amq-owner-sign is the owner's one step for a strict relay share.
|
Command amq-owner-sign is the owner's one step for a strict relay share. |
|
amq-remote
command
Package main: adapters.go is the single place adapter factory packages are linked into the shipped amq-remote binary.
|
Package main: adapters.go is the single place adapter factory packages are linked into the shipped amq-remote binary. |
|
internal
|
|
|
acp
Package acp implements the Agent Client Protocol (ACP) v2 AMQ bridge.
|
Package acp implements the Agent Client Protocol (ACP) v2 AMQ bridge. |
|
amqhome
Package amqhome owns the per-user AMQ home, ~/.amq.
|
Package amqhome owns the per-user AMQ home, ~/.amq. |
|
bridge/ring
Package ring is the content-free peer wake adapters: grokbot-webhook and slack-webhook, plus the start-of-mail and 14-day daily ring policy.
|
Package ring is the content-free peer wake adapters: grokbot-webhook and slack-webhook, plus the start-of-mail and 14-day daily ring policy. |
|
bridge/xferv3
Package xferv3 is the v3 transfer record: a length-prefixed content id with a signature stored beside it.
|
Package xferv3 is the v3 transfer record: a length-prefixed content id with a signature stored beside it. |
|
codexidentity
Package codexidentity keeps the AMQ identity that amq coop exec gave a Codex thread it created on Codex's shared app-server daemon.
|
Package codexidentity keeps the AMQ identity that amq coop exec gave a Codex thread it created on Codex's shared app-server daemon. |
|
format
Package format handles message serialization using JSON frontmatter with Markdown body content.
|
Package format handles message serialization using JSON frontmatter with Markdown body content. |
|
launch
Package launch defines the versioned contracts shared by launch orchestration, harness adapters, and terminal backends.
|
Package launch defines the versioned contracts shared by launch orchestration, harness adapters, and terminal backends. |
|
notificationattempt
Package notificationattempt persists a durable audit log of notification write attempts and their lifecycle so that `amq trace` and `amq doctor --ops` can report whether a wake attempted to notify an agent and what the outcome was.
|
Package notificationattempt persists a durable audit log of notification write attempts and their lifecycle so that `amq trace` and `amq doctor --ops` can report whether a wake attempted to notify an agent and what the outcome was. |
|
presence
Package presence manages agent presence metadata.
|
Package presence manages agent presence metadata. |
|
relay
Package relay is AMQ's Nostr relay transport (bead 611.15, relay design slice 1): one bounded WebSocket per relay and body identity, NIP-42 AUTH that presents exactly one enrolled NIP-OA tag, and publish that succeeds only on the relay's matching OK.
|
Package relay is AMQ's Nostr relay transport (bead 611.15, relay design slice 1): one bounded WebSocket per relay and body identity, NIP-42 AUTH that presents exactly one enrolled NIP-OA tag, and publish that succeeds only on the relay's matching OK. |
|
relay/relaytest
Package relaytest is an in-process Nostr relay for AMQ relay tests.
|
Package relaytest is an in-process Nostr relay for AMQ relay tests. |
|
remote/activity
Package activity projects native harness notifications into kind 24200 telemetry frames.
|
Package activity projects native harness notifications into kind 24200 telemetry frames. |
|
remote/amqio
Package amqio is the AMQ carrier for the remote endpoint: it imports commands from the endpoint's own handle mailbox and publishes replies and request revisions back as ordinary AMQ messages.
|
Package amqio is the AMQ carrier for the remote endpoint: it imports commands from the endpoint's own handle mailbox and publishes replies and request revisions back as ordinary AMQ messages. |
|
remote/binding
Package binding stores which live session the per-user Buzz agent drives.
|
Package binding stores which live session the per-user Buzz agent drives. |
|
remote/bodykey
Package bodykey implements the body-key contract of the AMQ Remote design (v3 amended, §7.5 "Key contract") and the NIP-OA Owner Attestation tag (buzz docs/nips/NIP-OA.md) that the owner uses to attest a body key.
|
Package bodykey implements the body-key contract of the AMQ Remote design (v3 amended, §7.5 "Key contract") and the NIP-OA Owner Attestation tag (buzz docs/nips/NIP-OA.md) that the owner uses to attest a body key. |
|
remote/buzzio
Package buzzio is the Buzz DM edge of the remote endpoint (bead 611.16, relay design §4).
|
Package buzzio is the Buzz DM edge of the remote endpoint (bead 611.16, relay design §4). |
|
remote/claude
Package claude is the Claude Code adapter factory (bead 611.12, PR1).
|
Package claude is the Claude Code adapter factory (bead 611.12, PR1). |
|
remote/codex
Package codex attaches to a running Codex CLI session through the shared local app-server daemon.
|
Package codex attaches to a running Codex CLI session through the shared local app-server daemon. |
|
remote/core
Package core is the amq-remote endpoint: it owns request identity and records, runs the admission algorithm against native attachments, applies native evidence, reconciles after a restart, and publishes revisions.
|
Package core is the amq-remote endpoint: it owns request identity and records, runs the admission algorithm against native attachments, applies native evidence, reconciles after a restart, and publishes revisions. |
|
remote/fake
Package fake is the controllable runtime the contract corpus drives.
|
Package fake is the controllable runtime the contract corpus drives. |
|
remote/ipc
Package ipc is the local carrier between the amq-remote CLI and the endpoint process: bounded, LF-framed JSON records over an owner-only Unix domain socket.
|
Package ipc is the local carrier between the amq-remote CLI and the endpoint process: bounded, LF-framed JSON records over an owner-only Unix domain socket. |
|
remote/jcs
Package jcs writes the RFC 8785 JSON Canonicalization Scheme form of a JSON text.
|
Package jcs writes the RFC 8785 JSON Canonicalization Scheme form of a JSON text. |
|
remote/linkcontract
Package linkcontract pins testdata/link: the golden amq.remote.link/1 frames, the signed consent document and the test keys behind them.
|
Package linkcontract pins testdata/link: the golden amq.remote.link/1 frames, the signed consent document and the test keys behind them. |
|
remote/linkio
Package linkio is the link carrier: one WebSocket that amq-remote dials to a linked server, carrying the server's commands down and the revisions AMQ owes up (protocol amq.remote.link/1, schemas/remote-link-v1.schema.json).
|
Package linkio is the link carrier: one WebSocket that amq-remote dials to a linked server, carrying the server's commands down and the revisions AMQ owes up (protocol amq.remote.link/1, schemas/remote-link-v1.schema.json). |
|
remote/manifest
Package manifest defines the companion adapter manifest: the single source of truth for which adapters a serve instance runs.
|
Package manifest defines the companion adapter manifest: the single source of truth for which adapters a serve instance runs. |
|
remote/pi
Package pi (bridge seam): deliver.go implements the adapter side of the pi-bridge protocol v1 paths:
|
Package pi (bridge seam): deliver.go implements the adapter side of the pi-bridge protocol v1 paths: |
|
remote/protocol
Package protocol defines the AMQ Remote application protocol: the command a client sends to an amq-remote endpoint, the request snapshot the endpoint answers with, and the session projection it advertises.
|
Package protocol defines the AMQ Remote application protocol: the command a client sends to an amq-remote endpoint, the request snapshot the endpoint answers with, and the session projection it advertises. |
|
remote/registry
Package registry is the capability-driven adapter registration seam.
|
Package registry is the capability-driven adapter registration seam. |
|
remote/requests
Package requests is the single-writer durable store for remote request records.
|
Package requests is the single-writer durable store for remote request records. |
|
remote/secretscan
Package secretscan tells whether text a remote surface would show may hold a secret, so the surface can show a notice instead.
|
Package secretscan tells whether text a remote surface would show may hold a secret, so the surface can show a notice instead. |
|
remote/sender
Drainer replays pending sender spool envelopes through the endpoint after a restart (and on each tick while the companion runs).
|
Drainer replays pending sender spool envelopes through the endpoint after a restart (and on each tick while the companion runs). |
|
remote/sharestate
Package sharestate is the read-only runtime view of a shared session's enrolled body identity (bead 611.15).
|
Package sharestate is the read-only runtime view of a shared session's enrolled body identity (bead 611.15). |
|
thread
Package thread collects and aggregates messages across agent mailboxes by thread ID.
|
Package thread collects and aggregates messages across agent mailboxes by thread ID. |
|
Package launchapi defines AMQ's versioned public launch-intent contract.
|
Package launchapi defines AMQ's versioned public launch-intent contract. |
|
scripts
|
|
|
amq-bot-envelope-hop-probe-tool
command
|