amq-cli

Agent Message Queue (AMQ)

A local, file-based interoperability bus for agent sessions and adapters.

AMQ manages the conversation: agent-to-agent messaging, thread continuity, cross-session and cross-project routing, handoff state, and operational visibility. It does not try to own task decomposition, worktree management, dependency scheduling, or scheduler execution; Claude Code teams, Codex, Kanban, Symphony, and similar orchestrators stay one layer above it.

Why AMQ?

Modern AI-assisted development often involves multiple agents working on the same codebase. But without coordination:

• Agents duplicate work or create conflicts
• Reviews require human intermediation
• Context switching kills productivity

AMQ gives agents a local interoperability bus: they can send messages, reply in threads, share status, and optionally consume adapter-emitted events through the same queue primitives. The core product stays intentionally small: file-based messages first, lightweight adapters second.

Key Features

• Zero infrastructure — Pure file-based. No server, no daemon, no database. Works anywhere files work.
• Crash-safe — Atomic Maildir delivery (tmp→new→cur). Messages are never partially written or lost.
• Human-readable — JSON frontmatter + Markdown body. Inspect with cat, debug with grep, version with git.
• Real-time notifications — amq wake injects terminal notifications when messages arrive (experimental).
• Built for agents — Priority levels, message kinds, threading, delivery receipts, and waitable handoffs.
• Cross-project federation — Route messages across peer repos, preserve reply routing, and run decision threads that span projects.
• Swarm mode — Join Claude Code Agent Teams, claim tasks, and bridge task notifications into AMQ.
• Optional adapters — Lightweight Symphony hooks and an experimental Kanban bridge can emit normal AMQ messages with structured metadata.
• Operational diagnostics — amq doctor --ops shows queue depth, DLQ state, presence freshness, and integration hints.

Installation

1. Install Binary

macOS (Homebrew):

brew install avivsinai/tap/amq

macOS/Linux (script):

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

Installs to ~/.local/bin or ~/go/bin (no sudo required). Verify: amq --version

One-liner with skill:

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

Review the script before running; it verifies release checksums when possible.

2. Install Skill

Via skills (recommended):

npx skills add avivsinai/agent-message-queue -g -y

Or via skild:

npx skild install @avivsinai/amq-cli -t claude -y

For manual installation or troubleshooting, see INSTALL.md.

Updating

amq upgrade

Quick Start

1. Initialize Project

amq coop init

Creates .amqrc, mailboxes for claude and codex, and updates .gitignore.

Optionally add shell aliases (amc for Claude, amx for Codex):

eval "$(amq shell-setup)"

2. Start Agent Sessions

# Terminal 1 — Claude Code
amc

# Terminal 2 — Codex CLI
amx

Each alias sets up the environment, starts wake notifications, and launches the agent. For isolated sessions (multiple pairs working on different features):

amc feature-a          # Claude in feature-a session
amx feature-a          # Codex in feature-a session

Without aliases, use amq coop exec directly:

amq coop exec claude -- --dangerously-skip-permissions
amq coop exec --session feature-a codex

Managed launchers can add --require-wake to fail instead of launching the agent when the wake watcher cannot start.

3. Send & Receive

# Send a message
amq send --to codex --subject "Review needed" --kind review_request \
  --body "Please review internal/cli/send.go"

# Check inbox
amq list --new

# Filter by priority or sender
amq list --new --priority urgent
amq list --new --from codex --kind review_request

# Read all messages (one-shot, moves to cur, emits drained/dlq receipts)
amq drain --include-body

# Wait for delivery on a single-recipient handoff
amq send --to codex --body "Please pick this up" \
  --wait-for drained --wait-timeout 60s