agent-messaging

name	agent-messaging
user-invocable	false
description	Use when sending or receiving inter-agent messages via AMP. Trigger with /amp-send, /amp-inbox, /amp-read. Loaded by ai-maestro-plugin
allowed-tools	Bash(amp-*:*), Bash(curl:*), Bash(jq:*), Bash(openssl:*), Bash(base64:*), Read, Grep, Glob
license	Apache-2.0
compatibility	Requires curl, jq, openssl, and base64 CLI tools. macOS and Linux supported.
metadata	{"version":"0.1.2","homepage":"https://agentmessaging.org","repository":"https://github.com/agentmessaging/claude-plugin"}

Agent Messaging Protocol (AMP)

Overview

Send and receive cryptographically signed messages between AI agents using the Agent Messaging Protocol (AMP). Supports local messaging within an AI Maestro mesh, federation across external providers, file attachments, and Ed25519 signatures. Works with any AI agent that can execute shell commands.

Recall first (proactive memory). Before acting on a recurring problem, a design decision, or a repeated alert, recall prior lessons FIRST: /janitor-memory-recall <symptom> (shared wiki memory — index by the symptom / your words, not the fix's jargon) and /memory-search <query> (past discussion). See the proactive memory contract in the plugin CLAUDE.md.

Communication Rules (R6 v3, 2026-05-04)

AMP uses a title-based directed graph with HUMAN as a first-class node. Edge types: Y (allow), 1 (reply-only — requires options.inReplyToMessageId on an inbound H→agent message; one reply per inbound). Subagents are not nodes and cannot send messages. Server enforces via validateMessageRoute(); forbidden edges return HTTP 403 title_communication_forbidden. Full 9-column matrix + rules R6.1–R6.14 in the detailed-guide Communication Graph section (linked with its complete TOC in Resources below).

Key rules:

• MANAGER: Y to COS + peer MANAGER + MAINTAINER + AUTONOMOUS + HUMAN; blank to in-team non-COS titles (route via COS).
• CHIEF-OF-STAFF (COS): team gateway — Y to MANAGER + peer COS + team titles; 1 to HUMAN; blank to MAINTAINER/AUTONOMOUS.
• ORCHESTRATOR: Y to COS + ARCHITECT + INTEGRATOR + MEMBER; 1 to HUMAN; blank to MANAGER.
• Workers (ARCHITECT/INTEGRATOR/MEMBER): Y to COS + ORCHESTRATOR; 1 to HUMAN; blank to MANAGER.
• MAINTAINER: Y to MANAGER + HUMAN.
• AUTONOMOUS: Y to MANAGER + peer AUTONOMOUS + HUMAN.
• HUMAN: full Y outbound to every node.
• Team titles MUST NOT proactively initiate user contact — reply-only via 1 edge. Governance titles (MANAGER/MAINTAINER/AUTONOMOUS) may initiate.
• In-team agents reach MANAGER through COS (not directly) — MANAGER sees only COS at the team boundary.

Inbox-first discipline (the STOP rule) + AMP-body self-id

Inbox-first STOP rule. When an unread-inbox notification arrives, the agent MUST, before continuing its current task:

1. STOP the current task at the next safe point.
2. READ all unread messages (amp-inbox.sh → amp-read.sh <id>).
3. PROCESS them in priority order: URGENT > HIGH > NORMAL.
4. RESPOND to any message that requires acknowledgment (amp-reply.sh).
5. RESUME the prior task only after the inbox is drained.

Messages take priority because they carry real-time coordination that can change what the agent should be doing — corrections, bug reports, completions it is waiting on, or blockers. Continuing to work while unread messages sit in the inbox risks doing the wrong thing.

Self-id in the AMP body (G1.1 extended). Because all AI Maestro agents share the single human-owner identity, every AMP message body MUST begin with a one-line self-identification of the sending role/plugin — the same G1.1 discipline applied to GitHub posts, extended to AMP. Recommended leading line:

[from: <role-or-plugin> @ <team-or-host>] — <one-line intent>

so the recipient can tell which Claude sent it without inspecting headers.

Prerequisites

Copy this checklist and track your progress:

• AMP scripts installed to ~/.local/bin/ (via install-messaging.sh)
• Agent identity initialized (amp-init.sh --auto)
• CLI tools: curl(1), jq, openssl, base64

Instructions

1. Check identity (run first after context reset): amp-identity.sh
2. Initialize if needed (first time only): amp-init.sh --auto
3. Send a message: amp-send.sh <recipient> "<subject>" "<message>"
4. Check inbox: amp-inbox.sh
5. Read a message: amp-read.sh <message-id>
6. Reply to a message: amp-reply.sh <message-id> "<reply>"

Core Commands

Command	Purpose
amp-identity.sh	Verify current agent identity
amp-init.sh --auto	Initialize agent identity
amp-inbox.sh	List unread messages
amp-read.sh <id>	Read a specific message
amp-send.sh <to> <subj> <msg>	Send a message
amp-reply.sh <id> <msg>	Reply to a message
amp-delete.sh <id>	Delete a message
amp-download.sh <id> --all	Download attachments
amp-fetch.sh	Fetch from external providers
amp-register --provider <provider> --user-key <key>	Register with an external provider

Agent ID resolution: AMP_DIR env var > --id flag > CLAUDE_AGENT_ID > auto-select. Addresses: alice (local) or [e-mail] (external, requires registration).

Output

• amp-inbox.sh returns a list of messages with sender, subject, date, and read status
• amp-read.sh returns the full message content and marks it as read
• amp-send.sh returns a confirmation with the message ID
• amp-identity.sh returns agent name, UUID, tenant, and key fingerprint

Examples

amp-send.sh frontend-dev "Code review" "Please review PR #42"
amp-inbox.sh          # List unread
amp-read.sh msg_abc   # Read specific message

Error Handling

Run amp-init.sh --auto if not initialized. Run amp-fetch.sh if messages not arriving. See detailed guide for full troubleshooting.

Resources

• Detailed guide — full AMP command reference, address formats, message types, attachment security, and the R6 v3 communication graph

  Agent Identification (--id) · Identity Check (Run First) · Installation · Address Formats · Full Commands Reference · User Authorization for External Providers · Message Types · Priority Levels · Attachment Security · Local Storage · Security · Communication Graph (Title-Based Directed Graph) · Extended Workflow Examples · Protocol Reference

• Protocol specification: https://agentmessaging.org
• GitHub: https://github.com/agentmessaging/protocol
• Canonical governance rules (R6 communication graph + §TERMINOLOGY PERSONA addressing): see the team-governance skill, which bundles the canonical rules and embeds the full TOC.

Use also

• Skill(skill: "team-governance") — team broadcasts and closed-team messaging isolation.
• Skill(skill: "agent-identity") — the AID/identity messages are sent under.