Skip to content

hashgraph-online/awesome-codex-plugins / plugins/avivsinai/agent-message-queue/skills/amq-cli

amq-cli

Verified

Coordinate 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.

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.
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall