{"id":34795479,"url":"https://github.com/avivsinai/agent-message-queue","last_synced_at":"2026-04-05T08:01:51.460Z","repository":{"id":330412101,"uuid":"1122637774","full_name":"avivsinai/agent-message-queue","owner":"avivsinai","description":"File-based message queue for local agent-to-agent communication (Maildir-style)","archived":false,"fork":false,"pushed_at":"2026-03-30T09:27:15.000Z","size":4297,"stargazers_count":36,"open_issues_count":2,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T11:33:32.063Z","etag":null,"topics":["agent-skills","agents","ai-agents","autonomous-agents","claude-code","cli","codex","coordination","developer-tools","golang","inter-process-communication","maildir","message-queue","multi-agent"],"latest_commit_sha":null,"homepage":"https://github.com/avivsinai/agent-message-queue","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avivsinai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-25T07:18:14.000Z","updated_at":"2026-03-30T09:27:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/avivsinai/agent-message-queue","commit_stats":null,"previous_names":["avivsinai/agent-message-queue"],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/avivsinai/agent-message-queue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Fagent-message-queue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Fagent-message-queue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Fagent-message-queue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Fagent-message-queue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avivsinai","download_url":"https://codeload.github.com/avivsinai/agent-message-queue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Fagent-message-queue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31308446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","agents","ai-agents","autonomous-agents","claude-code","cli","codex","coordination","developer-tools","golang","inter-process-communication","maildir","message-queue","multi-agent"],"created_at":"2025-12-25T10:42:47.232Z","updated_at":"2026-04-02T14:49:14.013Z","avatar_url":"https://github.com/avivsinai.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Message Queue (AMQ)\n\n[![CI](https://github.com/avivsinai/agent-message-queue/actions/workflows/ci.yml/badge.svg)](https://github.com/avivsinai/agent-message-queue/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/avivsinai/agent-message-queue)](https://github.com/avivsinai/agent-message-queue/releases/latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**A local, file-based interoperability bus for agent sessions and adapters.**\n\nAMQ 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.\n\n## Why AMQ?\n\nModern AI-assisted development often involves multiple agents working on the same codebase. But without coordination:\n- Agents duplicate work or create conflicts\n- Reviews require human intermediation\n- Context switching kills productivity\n\nAMQ 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.\n\n### Key Features\n\n- **Zero infrastructure** — Pure file-based. No server, no daemon, no database. Works anywhere files work.\n- **Crash-safe** — Atomic Maildir delivery (tmp→new→cur). Messages are never partially written or lost.\n- **Human-readable** — JSON frontmatter + Markdown body. Inspect with `cat`, debug with `grep`, version with `git`.\n- **Real-time notifications** — `amq wake` injects terminal notifications when messages arrive (experimental).\n- **Built for agents** — Priority levels, message kinds, threading, acknowledgments—all the primitives agents need.\n- **Cross-project federation** — Route messages across peer repos, preserve reply routing, and run decision threads that span projects.\n- **Swarm mode** — Join Claude Code Agent Teams, claim tasks, and bridge task notifications into AMQ.\n- **Optional adapters** — Lightweight Symphony hooks and an experimental Kanban bridge can emit normal AMQ messages with structured metadata.\n- **Operational diagnostics** — `amq doctor --ops` shows queue depth, DLQ state, presence freshness, pending acks, and integration hints.\n\n![AMQ Demo — Claude and Codex collaborating via split-pane terminal](docs/assets/demo.gif)\n\n## Installation\n\n### 1. Install Binary\n\n**macOS (Homebrew):**\n```bash\nbrew install avivsinai/tap/amq\n```\n\n**macOS/Linux (script):**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash\n```\n\nInstalls to `~/.local/bin` or `~/go/bin` (no sudo required). Verify: `amq --version`\n\n**One-liner with skill:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash -s -- --skill\n```\n\nReview the script before running; it verifies release checksums when possible.\n\n### 2. Install Skill\n\n**Via skills** (recommended):\n```bash\nnpx skills add avivsinai/agent-message-queue -g -y\n```\n\n**Or via skild:**\n```bash\nnpx skild install @avivsinai/amq-cli -t claude -y\n```\n\nFor manual installation or troubleshooting, see [INSTALL.md](INSTALL.md).\n\n### Updating\n\n```bash\namq upgrade\n```\n\n## Quick Start\n\n### 1. Initialize Project\n\n```bash\namq coop init\n```\n\nCreates `.amqrc`, mailboxes for `claude` and `codex`, and updates `.gitignore`.\n\nOptionally add shell aliases (`amc` for Claude, `amx` for Codex):\n```bash\neval \"$(amq shell-setup)\"\n```\n\n### 2. Start Agent Sessions\n\n```bash\n# Terminal 1 — Claude Code\namc\n\n# Terminal 2 — Codex CLI\namx\n```\n\nEach alias sets up the environment, starts wake notifications, and launches the agent. For isolated sessions (multiple pairs working on different features):\n\n```bash\namc feature-a          # Claude in feature-a session\namx feature-a          # Codex in feature-a session\n```\n\nWithout aliases, use `amq coop exec` directly:\n```bash\namq coop exec claude -- --dangerously-skip-permissions\namq coop exec --session feature-a codex\n```\n\n### 3. Send \u0026 Receive\n\n```bash\n# Send a message\namq send --to codex --subject \"Review needed\" --kind review_request \\\n  --body \"Please review internal/cli/send.go\"\n\n# Check inbox\namq list --new\n\n# Filter by priority or sender\namq list --new --priority urgent\namq list --new --from codex --kind review_request\n\n# Read all messages (one-shot, moves to cur, auto-acks)\namq drain --include-body\n\n# Reply to a message\namq reply --id \u003cmsg_id\u003e --kind review_response --body \"LGTM with comments\"\n```\n\n### 4. Inspect Health\n\n```bash\namq doctor\namq doctor --ops\namq doctor --ops --json\n```\n\n## Message Kinds \u0026 Priority\n\nAMQ messages support kinds (`review_request`, `question`, `todo`, etc.) and priority levels (`urgent`, `normal`, `low`). See [COOP.md](COOP.md) for the full protocol.\n\n## Co-op Mode\n\nFor real-time Claude Code + Codex CLI collaboration patterns, roles, and phased workflows, see [COOP.md](COOP.md).\n\n## Cross-Project Federation\n\nAMQ can route messages across repositories, not just across agents in one checkout. Add a project name plus peer roots to `.amqrc`:\n\n```json\n{\n  \"root\": \".agent-mail\",\n  \"project\": \"app\",\n  \"peers\": {\n    \"infra-lib\": \"/Users/me/src/infra-lib/.agent-mail\"\n  }\n}\n```\n\nThen send directly to another project:\n\n```bash\namq send --to codex --project infra-lib --body \"Can you review the shared API change?\"\namq send --to codex@infra-lib:collab --thread decision/release-v0.24 --kind decision \\\n  --labels \"decision:proposal,project:app,project:infra-lib\" \\\n  --body \"Proposal: align both repos on v0.24\"\n```\n\nReplies route back automatically with the stamped `reply_project` metadata. When `from` matches your own handle, inspect `from_project` before treating the message as an echo; the same handle in a different project is a legitimate cross-project sender. This shipped in v0.22.0 and is the recommended way to coordinate multi-repo agent work without adding a broker.\n\n## Swarm Mode (Claude Code Agent Teams)\n\nExternal agents (Codex, etc.) can join Claude Code Agent Teams via `amq swarm join`, claim tasks, and receive notifications through `amq swarm bridge`. Note: the bridge delivers task notifications only; direct messages require relay through the team leader.\n\nFor the full command reference, see [CLAUDE.md](CLAUDE.md).\n\n## Global Root Fallback\n\nMost AMQ commands resolve the queue root from the project `.amqrc`. For agents launched outside the repo root by external orchestrators, you can configure a global fallback instead:\n\n```bash\nexport AMQ_GLOBAL_ROOT=\"$HOME/.agent-mail\"\n```\n\nOr create `~/.amqrc`:\n\n```json\n{\"root\": \".agent-mail\"}\n```\n\nRoot resolution precedence is:\n\n```text\nflags \u003e AM_ROOT \u003e project .amqrc \u003e AMQ_GLOBAL_ROOT \u003e ~/.amqrc \u003e auto-detect\n```\n\nThis same chain is used by `amq env`, `amq doctor`, and the integration commands, so Symphony and Kanban-launched agents can find the correct queue even when they are not started from the project directory.\n\n## Integrations\n\nAMQ transports **messages**, not remote task state. The integration layer is intentionally narrow: optional adapters convert external lifecycle or task events into normal AMQ messages. Integration messages are self-delivered (`from=\u003cme\u003e`, `to=\u003cme\u003e`) so an agent monitoring its own inbox can react without polling another tool directly.\n\n### Symphony\n\nSymphony support is a lightweight hook recipe for Codex workspaces orchestrated through `WORKFLOW.md`:\n\n```bash\namq integration symphony init --me codex\namq integration symphony init --me codex --check\namq integration symphony emit --event after_run --me codex\n```\n\n`init` patches an AMQ-managed fragment into `WORKFLOW.md`. `emit` is hook-friendly and supports `after_create`, `before_run`, `after_run`, and `before_remove`. This stays intentionally small: AMQ does not try to become a Symphony control plane. Current limitation: because `WORKFLOW.md` is parsed and rewritten as structured YAML/Markdown, comments and formatting inside the frontmatter may be normalized.\n\n### Cline Kanban Bridge\n\nThe Kanban bridge is **experimental**. Use it when you want runtime session transitions and review handoffs mirrored into AMQ, with the understanding that it depends on a fast-moving preview WebSocket surface:\n\n```bash\namq integration kanban bridge --me codex\namq integration kanban bridge --me codex --workspace-id my-workspace\n```\n\nThe bridge connects to `ws://127.0.0.1:3484/api/runtime/ws` by default, bootstraps from `snapshot`, refreshes from `workspace_state_updated`, and emits notifications only for task session transitions plus `task_ready_for_review`.\n\n### Integration Metadata\n\nThe built-in adapters share a versioned contract under `context.orchestrator`. See [docs/adapter-contract.md](docs/adapter-contract.md) for the formal v1 envelope and stability expectations.\n\nIntegration messages also carry standard labels such as:\n\n- `orchestrator`\n- `orchestrator:symphony` or `orchestrator:kanban`\n- `task-state:\u003cstate\u003e`\n- `handoff` for review-ready transitions\n- `blocking` for failed or interrupted work\n\nThat makes integration traffic filterable with existing AMQ primitives such as `amq list --label orchestrator --label handoff`.\n\n## Command Reference\n\nCommon command groups:\n\n| Area | Commands |\n|------|----------|\n| Core messaging | `init`, `send`, `list`, `read`, `drain`, `reply`, `thread`, `ack`, `watch`, `monitor` |\n| Collaboration | `coop init`, `coop exec`, `swarm list`, `swarm join`, `swarm tasks`, `swarm bridge` |\n| Integrations | `integration symphony init`, `integration symphony emit`, `integration kanban bridge` |\n| Operations | `presence set`, `presence list`, `who`, `doctor`, `doctor --ops`, `cleanup`, `dlq *`, `upgrade`, `env`, `shell-setup` |\n\nFor the full CLI syntax, examples, and message schema, see [CLAUDE.md](CLAUDE.md).\n\n## How It Works\n\nAMQ uses the battle-tested [Maildir](https://cr.yp.to/proto/maildir.html) format:\n\n1. **Write** — Message written to `tmp/` directory\n2. **Sync** — File fsynced to disk\n3. **Deliver** — Atomic rename to `new/` (never partial)\n4. **Process** — Reader moves to `cur/` after reading\n\nThis guarantees crash-safety: if the process dies mid-write, no corrupt message appears in the inbox. See [CLAUDE.md](CLAUDE.md) for the full directory layout.\n\n## Documentation\n\n- [INSTALL.md](INSTALL.md) — Alternative installation methods\n- [docs/adapter-contract.md](docs/adapter-contract.md) — Formal v1 adapter contract for integration messages\n- [COOP.md](COOP.md) — Co-op mode protocol \u0026 best practices\n- [CLAUDE.md](CLAUDE.md) — Agent instructions, CLI reference, architecture\n\n## Development\n\n```bash\ngit clone https://github.com/avivsinai/agent-message-queue.git\ncd agent-message-queue\nmake build   # Build binary\nmake test    # Run tests\nmake ci      # Full CI: vet + lint + test + smoke\n```\n\n## FAQ\n\n**Why not just use a database?**\nFiles are universal, debuggable, and work everywhere. No connection strings, no migrations, no ORM. Just files.\n\n**Why not Redis/RabbitMQ/etc?**\nThose require infrastructure. AMQ is for local inter-process communication where agents share a filesystem. No server to configure or keep running.\n\n**What about Windows?**\nThe core queue works on Windows. The `amq wake` notification feature requires WSL.\n\n**Is this production-ready?**\nFor local development workflows, yes. AMQ is intentionally simple—it's not trying to be a distributed message broker.\n\n**How does AMQ compare to other multi-agent tools?**\nTools like [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) (server-based coordination + SQLite), [Gas Town](https://github.com/steveyegge/gastown) (tmux-based orchestration), and others offer richer features. AMQ is intentionally minimal: single binary, no server, Maildir delivery. Best for 2-3 agents on one machine.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favivsinai%2Fagent-message-queue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favivsinai%2Fagent-message-queue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favivsinai%2Fagent-message-queue/lists"}