hashgraph-online/awesome-codex-plugins / plugins/avivsinai/agent-message-queue/skills/amq-cli
amq-cli
VerifiedCoordinate coding agents through AMQ. Use for agent messages, inboxes, receipts, sessions, wake delivery, cross-project routing, managed launches, or AMQ diagnostics. Use amq-spec for collaborative design; do not use this for general message queues or single-agent work.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.8 KB |
| references/coop-mode.md | markdown | 5.8 KB |
| references/cross-project.md | markdown | 6.9 KB |
| references/integrations.md | markdown | 2.6 KB |
| references/message-format.md | markdown | 4.7 KB |
| references/operations.md | markdown | 32.0 KB |
| references/registered-machine.md | markdown | 6.0 KB |
| references/review-loop.md | markdown | 1.8 KB |
| references/swarm-mode.md | markdown | 2.3 KB |
references/cross-project.md
View on GitHub# Cross-Project Messaging
Send messages between agents in different projects. Requires peer configuration in `.amqrc`.
## Peer Configuration
Each project's `.amqrc` maps peer names to their base root paths:
```json
{
"root": ".agent-mail",
"project": "proj-a",
"peers": {
"proj-b": "/Users/me/projects/proj-b/.agent-mail"
}
}
```
- `project`: explicit self-identity (defaults to directory basename if absent)
- `peers`: name → absolute path to peer's base root
**Critical naming rule**: Peer keys must match the remote project's declared `project` name (or its directory basename if `project` is absent). Reply routing uses `reply_project` which is set to the sender's project identity — the receiver must have a peer entry with that exact name. If project A calls its peer `backend` but that project identifies as `api-server`, replies from `api-server` will fail because A has no peer named `api-server`.
Both projects must register each other as peers for round-trip messaging.
Run `amq route peers` to check this: each peer shows `reply_back: no` when its
`.amqrc` lacks your exact project name. `amq route explain --json` shows which
`.amqrc` and peer key decided a route (`source_config`, `peer_key`).
`amq trace <id> --follow --from <you>` shows which project and session holds each
recipient's copy and receipt, and for a request whether the reply came back and was
drained; `amq thread open --follow --json` does this for every open request.
Route with `--project` or `--session`, not a raw `--root`. A direct `--root`
selects which tree to operate on and carries no sender-origin metadata, so the
recipient cannot reply. `amq send` refuses an explicit `--root` that crosses
into a different base tree than the active session (`AM_ROOT`/`AM_BASE_ROOT`)
when no `--project`, `--session`, or `--from-session` is given. If a send is
genuinely local, set the target as your `AM_ROOT` instead.
## Addressing
### Flag syntax (explicit)
```bash
amq send --to codex --project proj-b --body "hello"
amq send --to codex --project proj-b --session auth --body "to specific session"
```
### Inline syntax (terser)
```bash
amq send --to codex@proj-b --body "hello"
amq send --to codex@proj-b:auth --body "to specific session"
```
Flags take precedence over inline syntax.
After a cross-project send, `AM_ROOT` still points to your own project. Send to
a partner in your own project with plain `amq send --to <handle>`, without
`--project`.
## Same-Handle Messages
A matching sender and recipient handle has three distinct meanings:
| Route | Meaning |
|---|---|
| `--project` is present | A different agent instance in another project. AMQ stamps `from_project` and reply routing metadata. |
| `--session` or `--from-session` is present | A different agent instance in another session. AMQ stamps session reply routing metadata. |
| No routing dimension is present | A same-root self-send with no provenance beyond the handle. `amq send` refuses it by default. |
Use `--allow-self` only to confirm an intentional same-root self-send. The flag
does not make `--root` a routing dimension, add reply metadata, or bypass the
cross-tree and session-pin guards. To reach another instance of your handle,
use `--project` or `--session` instead; routed same-handle sends do not require
`--allow-self`.
On receipt, a message whose `from` is your own handle but whose `from_project`
or `reply_project` names another project is not an echo. It comes from another
agent instance; process it normally.
## Session Defaults
`--project proj-b` without `--session` delivers to the **same session name** in the peer project. If your source root is `.agent-mail/collab`, the message goes to `proj-b's .agent-mail/collab`. Override with explicit `--session`.
## Reply Routing
Cross-project messages carry `reply_project` and `reply_to`. The latter is
`handle@session` for a named session and the bare handle for a base-root sender.
To answer, use the message ID:
```bash
amq reply --id "<msg_id>" --body "got it"
```
The CLI reads `reply_project` from the message, resolves the peer, and delivers to the correct project/session. The reply re-stamps `reply_to` and `reply_project` with the replier's own identity for continued round-trip.
## Thread Naming
- **Same project P2P**: `p2p/claude__codex`
- **Cross-session P2P**: `p2p/collab:claude__auth:codex`
- **Cross-project P2P**: `p2p/proj-a:collab:claude__proj-b:collab:codex`
- **Topical threads**: Use the same thread ID across all participating projects (e.g., `decision/api-v2`, `review/auth-module`)
## Safety
- Cross-project delivery **never creates directories** in the peer project. The target inbox must already exist (created by `amq init` or `amq coop init` in the peer project). This prevents accidental scaffolding.
- Peer paths must be absolute (or relative to the `.amqrc` directory).
- A project name with no peer entry in `.amqrc` fails and lists the known peers.
## Decision Threads
Decentralized decision protocol for cross-project coordination, based on RFC 7282 rough consensus. Uses existing AMQ primitives — no new CLI commands.
### Process
1. **Propose**: Send a `decision` kind message on thread `decision/<topic>` with label `decision:proposal`
2. **Review/Object**: Participants reply with `decision:support` or `decision:objection` labels. Add `blocking` label for unresolved objections.
3. **Resolve**: Address blocking objections. Running code (tests) is stronger evidence than arguments.
4. **Close**: When all required projects have responded and no unresolved blocking objections remain, send `decision:final`.
### Convention
```bash
# Proposal
amq send --to codex --project proj-b --kind decision \
--labels "decision:proposal,project:proj-a,project:proj-b" \
--thread "decision/api-v2" \
--context '{"proposal_id":"api-v2","question":"Adopt new API?","required_projects":["proj-a","proj-b"]}' \
--body "Proposal: migrate to API v2. Please review the consumer contract."
# Support
amq reply --id "<msg_id>" --kind decision \
--labels "decision:support" \
--body "The proposed contract meets our requirements."
# Objection
amq reply --id "<msg_id>" --kind decision \
--labels "decision:objection,blocking" \
--body "Breaks backward compat for our consumers."
# Final decision
amq reply --id "<msg_id>" --kind decision \
--labels "decision:final" \
--body "Agreed: retain backward compatibility for existing consumers."
```
### Context schema for proposals
```json
{
"proposal_id": "api-v2",
"question": "Should we adopt the new API?",
"options": ["adopt", "defer", "reject"],
"required_projects": ["proj-a", "proj-b"],
"deadline": "<agreed deadline>",
"evidence": ["<path or URL to observed results>"]
}
```
## What NOT to use cross-project for
- **Same project, different session**: Use `--session` instead
- **Swarm mode**: Agent teams are project-scoped. Use AMQ bridge for swarm notifications within a project.
- **Broadcasting**: No `--to @all` across projects. Send individually to each peer.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |