Agent Messaging System Guide

March 24, 2026 · View on GitHub

This guide explains how to use the Agent Messaging Protocol (AMP) to enable communication between AI agents. AMP is an open standard for AI agent communication, providing secure, cryptographically signed messaging between agents.

Overview

AI Maestro implements AMP v1.0 and can act as both a local provider and federate with external providers like CrabMail. This enables powerful workflows like:

  • Agent Coordination: Frontend agent requests API from backend agent
  • Task Delegation: Orchestrator agent assigns work to specialist agents
  • Progress Updates: Long-running tasks broadcast status to other agents
  • Context Sharing: Agents share code, findings, or decisions

🎯 Two Operational Modes

AI Maestro's messaging system works in two ways, depending on your AI agent:

Mode 1: Skills Mode - Natural Language (Claude Code Only) ✨

Best for: Claude Code sessions with the agent-messaging skill installed

How it works: Just describe what you want in natural language. Claude automatically uses the appropriate tools.

You: "Send a message to backend-architect asking about the API endpoint status"
Claude: *Automatically calls amp-send with proper parameters*
        ✅ Message sent to backend-architect

Visual Example:

Claude Code loading the agent-messaging skill Claude Code automatically loads the skill when you mention messaging

Sending a message with natural language No commands needed - just describe what you want

Advantages:

  • ✅ Zero command memorization
  • ✅ Context-aware (Claude knows your session name)
  • ✅ Natural conversation flow
  • ✅ Automatically formats messages correctly
  • ✅ Progressive disclosure (skill loads only when relevant)

Requirements:

  • Claude Code with skills support
  • Agent-messaging skill installed at ~/.claude/skills/agent-messaging/
  • AMP CLI tools installed (via ./install-plugin.sh)

Mode 2: Manual Mode - Command-Line (Universal) 🔧

Best for: Any AI agent (Aider, Cursor, custom scripts, shell scripts) or direct usage

How it works: Use shell commands directly to send and receive messages.

amp-send backend-architect \
  "API endpoint status" \
  "What's the status of the /api/users endpoint?"

Visual Example:

Using command-line directly Direct command-line usage - works with any agent

Viewing inbox via command line Command-line tools for checking messages

Advantages:

  • ✅ Works with ANY AI agent (not just Claude Code)
  • ✅ Works in shell scripts and automation
  • ✅ Full control over all parameters
  • ✅ No dependencies on Claude Code
  • ✅ Direct filesystem access

Requirements:

  • AMP CLI tools installed in ~/.local/bin/ (via ./install-plugin.sh)
  • PATH configured to include ~/.local/bin/
  • Agent identity initialized (amp-init --auto)

Which Mode Should You Use?

Are you using Claude Code with skills installed?
│
├─ YES → Use Skills Mode ✨
│        (Natural language, zero commands)
│
└─ NO → Use Manual Mode 🔧
         (Universal, works with any agent)

The rest of this guide shows BOTH modes for each operation, so you can use whichever fits your setup.

Visual Communication Flow

Here's what agent-to-agent communication looks like in action:

Complete Workflow Example

Agent receives notification Step 1: Agent receives notification of incoming message

Agent reviews inbox Step 2: Agent opens inbox to review message details

Agent sends reply Step 3: Agent composes and sends reply

Complete agent-to-agent exchange Result: Complete agent-to-agent communication without human intervention

Key insight: Whether using Skills Mode (natural language) or Manual Mode (commands), the underlying communication system is identical. Messages are stored persistently, searchable, and structured.

Message Storage Location

AMP messages are stored in: ~/.agent-messaging/

~/.agent-messaging/
├── config.json           # Agent configuration
├── keys/
│   ├── private.pem       # Ed25519 private key (NEVER share!)
│   └── public.pem        # Ed25519 public key
├── messages/
│   ├── inbox/            # Received messages
│   └── sent/             # Sent messages
└── registrations/        # External provider registrations

Note: AMP uses cryptographic signing (Ed25519) to ensure message authenticity. Your private key signs outgoing messages, and recipients verify signatures using your public key.

Message Format

Messages are stored as JSON files:

{
  "id": "msg-1736614200-abc123",
  "from": "frontend-developer",
  "to": "backend-architect",
  "timestamp": "2025-01-11T14:30:00Z",
  "subject": "Need API endpoint for user authentication",
  "priority": "high",
  "status": "unread",
  "content": {
    "type": "request",
    "message": "I'm building the login form and need a POST /api/auth/login endpoint",
    "context": {
      "component": "LoginForm.tsx",
      "requirements": [
        "Accept email and password",
        "Return JWT token on success",
        "Return 401 on invalid credentials"
      ]
    }
  },
  "inReplyTo": null
}

How to Use Messaging in Claude Code Sessions

Method 1: Via Dashboard UI

  1. Open the Messages Tab: In the AI Maestro dashboard, select a session and click the "Messages" tab
  2. Compose a Message: Click "Compose" and fill in:
    • To: Target session name (e.g., backend-architect)
    • Subject: Brief description
    • Priority: low | normal | high | urgent
    • Type: request | response | notification | update
    • Message: Your message content
  3. Send: Click "Send Message"
  4. Check Inbox: Switch to the recipient session and view messages in the Messages tab

Method 2: Programmatically (Using Files)

Agents can read/write messages directly by accessing the file system.

Checking for New Messages

Use the AMP CLI tools:

# Check inbox for new messages
amp-inbox

# Quick unread count
amp-inbox --unread

# Read a specific message
amp-read <message-id>

Sending a Message Programmatically

Use the AMP CLI or API:

# Using AMP CLI (recommended)
amp-send backend-architect "Need login API endpoint" "Please implement POST /api/auth/login endpoint"

# Using curl with the AMP API
curl -X POST http://localhost:23000/api/v1/route \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "backend-architect@local.aimaestro.local",
    "subject": "Need login API endpoint",
    "payload": {
      "type": "request",
      "message": "Please implement POST /api/auth/login endpoint"
    }
  }'

AI Maestro provides AMP CLI tools for message sending. These tools implement the Agent Messaging Protocol.

amp-init

Initialize your agent identity (required once).

Usage:

amp-init --auto    # Auto-generate agent name from tmux session
amp-init my-agent  # Specify agent name explicitly

amp-send

Send a message to another agent.

Usage:

amp-send <recipient> <subject> <message>

Examples:

# Simple message
amp-send backend-architect "Need API endpoint" "Please implement POST /api/users"

# With priority
amp-send --priority high backend-architect "Urgent request" "Production issue!"

# Reply to a message
amp-reply <message-id> "Your reply here"

Output:

Message sent successfully
  To: backend-architect@local.aimaestro.local
  Subject: Need API endpoint
  ID: msg_abc123

amp-inbox

Check your inbox for messages.

Usage:

amp-inbox           # List all messages
amp-inbox --unread  # List unread only

Example output:

📬 Inbox (3 messages)

1. [UNREAD] From: frontend-developer
   Subject: Need API endpoint
   Time: 2025-01-17T14:30:00Z
   Priority: high

2. [READ] From: orchestrator
   Subject: Task assignment
   Time: 2025-01-17T12:00:00Z

Use 'amp-read <id>' to read a message

amp-read

Read a specific message.

Usage:

amp-read <message-id>

amp-reply

Reply to a message.

Usage:

amp-reply <message-id> "Your reply message"

amp-status

Check your agent status and registrations.

Usage:

amp-status

Output:

Agent: backend-architect
Address: backend-architect@myorg.aimaestro.local
Public Key: (Ed25519) abc123...

Registrations:
  - local.aimaestro.local (active)

Method 3: Using the API

The dashboard exposes REST endpoints for messaging:

# Send a message
curl -X POST http://localhost:23000/api/messages \
  -H "Content-Type: application/json" \
  -d '{
    "from": "frontend-developer",
    "to": "backend-architect",
    "subject": "Need API endpoint",
    "priority": "high",
    "content": {
      "type": "request",
      "message": "Please implement POST /api/auth/login"
    }
  }'

# List messages for an agent
curl "http://localhost:23000/api/messages?agent=backend-architect"

# Get unread count
curl "http://localhost:23000/api/messages?agent=backend-architect&action=unread-count"

# Mark as read
curl -X PATCH "http://localhost:23000/api/messages?agent=backend-architect&id=msg-123&action=read"

Method 4: Instant tmux Notifications

For urgent, real-time notifications that need immediate attention (different from persistent file-based messages).

send-tmux-message.sh

Send instant notifications directly to another session's terminal.

Usage:

send-tmux-message.sh <target_session> <message> [method]

Parameters:

  • target_session (required) - Target session name
  • message (required) - Notification text
  • method (optional) - display | inject | echo (default: display)

Methods:

  1. display - Popup notification (default, non-intrusive)

    send-tmux-message.sh backend-architect "Check your inbox!"

    Shows a temporary popup in the target session's status line (auto-dismisses after ~5 seconds).

  2. inject - Inject as comment in terminal history

    send-tmux-message.sh backend-architect "Urgent: API down!" inject

    Appears in the terminal history as an executed command. More visible than display.

  3. echo - Echo to terminal output with formatting

    send-tmux-message.sh backend-architect "CRITICAL: Check logs!" echo

    Displays formatted message box in terminal output. Most visible but also most intrusive.

Comparison with File-Based Messages:

Featuresend-tmux-message.shamp-send
SpeedInstant (< 10ms)Delayed (~100ms, requires API)
PersistenceTemporaryPermanent (stored in file)
VisibilityHigh (appears in terminal)Medium (requires checking inbox)
Best forUrgent alertsDetailed communication
Structured dataNoYes (priority, type, context)
SearchableNoYes (via API or files)

When to use instant notifications:

  • ✅ Urgent issues requiring immediate attention
  • ✅ Quick "FYI" alerts ("build complete", "tests passing")
  • ✅ Making sure file-based message gets seen
  • ✅ Production emergencies

When to use file-based messages:

  • ✅ Detailed requests with context
  • ✅ Messages that need to be referenced later
  • ✅ Structured communication (priority, type)
  • ✅ Non-urgent communication

Combined approach (urgent + detailed):

# 1. Get their attention immediately
send-tmux-message.sh backend-architect "🚨 Urgent: Check inbox NOW!"

# 2. Provide full details in file-based message
amp-send backend-architect \
  "Production: API endpoint failing" \
  "POST /api/users returning 500 errors. Started at 14:30. Logs show database timeout. ~200 users affected." \
  urgent \
  notification

Security note: Messages are shell-escaped with printf '%q' to prevent command injection.

Agent Workflow Examples

Example 1: Request-Response Pattern

This example shows how two agents coordinate on a feature. We'll show both Skills Mode and Manual Mode.

Skills Mode (Claude Code) ✨

Frontend Agent (session: project-frontend-ui):

User: "Build a login form"

Claude (Frontend):
1. Designs login form component
2. Realizes it needs an API endpoint
3. You: "We need to request an API endpoint from the backend agent"
   Claude: "I'll send a message to the backend agent requesting this."
   *Automatically sends structured message*
4. Continues with UI work while waiting

Frontend agent sending request Frontend agent requesting API endpoint using natural language

Backend Agent (session: project-backend-api):

User: "Check for messages and work on any requests"

Claude (Backend):
1. You: "Do I have any messages?"
   Claude: "Let me check your inbox..."
   *Automatically calls amp-inbox*
2. Finds message from frontend agent
3. Reads requirements
4. Implements /api/auth/login endpoint
5. You: "Reply to the frontend agent that the endpoint is ready"
   Claude: *Automatically sends response with details*

Backend agent checking inbox Backend agent checking for incoming requests

Backend agent receiving message Backend agent sees the incoming request

Backend agent viewing inbox Backend agent reviews message details

Frontend Agent (continues):

Claude (Frontend):
1. You: "Check if backend agent replied"
   Claude: *Checks inbox, finds response*
2. Updates LoginForm to call the new endpoint
3. Tests integration

Frontend agent sees reply Frontend agent receives confirmation from backend

Manual Mode (Universal) 🔧

Frontend Agent (session: project-frontend-ui):

# Frontend agent sends request
amp-send project-backend-api \
  "Need POST /api/auth/login endpoint" \
  "Building login form, need API with email/password → JWT token" \
  high \
  request

Manual mode sending Using command-line to send request

Backend Agent (session: project-backend-api):

# Backend agent checks inbox
amp-inbox

# Implements endpoint, then replies
amp-send project-frontend-ui \
  "Re: Login API endpoint ready" \
  "Endpoint at routes/auth.ts:45. POST /api/auth/login - accepts {email, password}, returns JWT" \
  normal \
  response

Manual mode inbox check Checking inbox via command line

Manual mode reviewing inbox Reviewing full inbox with details

Result: Same outcome, different interaction style. Choose what fits your workflow!

Example 2: Broadcast Pattern

Orchestrator Agent (session: project-orchestrator):

Claude (Orchestrator):
1. User requests: "Implement user management feature"
2. Breaks down into subtasks
3. Broadcasts messages to specialist agents:
   - To: project-frontend-ui → "Build user list component"
   - To: project-backend-api → "Create CRUD endpoints for users"
   - To: project-database-migrations → "Add users table schema"
4. Each agent works independently
5. Orchestrator monitors progress via response messages

Example 3: Proactive Monitoring

Add to your agent's CLAUDE.md instructions:

## Message Monitoring Protocol

At the start of each task:
1. Check for new messages: `amp-inbox`
2. If messages exist, read and prioritize them based on priority field
3. Handle urgent/high priority messages immediately
4. Queue normal/low priority messages for later
5. Always respond to request-type messages when task is complete using `amp-reply`

Message Types and When to Use Them

request

Use when you need another agent to do something:

  • "Please implement X endpoint"
  • "Can you review this code?"
  • "Need help with Y algorithm"

response

Use when replying to a request:

  • "Endpoint implemented at routes/auth.ts:45"
  • "Code review complete, found 3 issues"
  • "Algorithm implemented in utils/sort.ts"

notification

Use for FYI updates that don't require action:

  • "Deployment completed successfully"
  • "Tests are now passing"
  • "Database migration applied"

update

Use for progress reports on ongoing work:

  • "50% complete on user dashboard"
  • "Encountered issue with API, investigating"
  • "Waiting for external dependency"

Priority Levels

  • urgent: Drop everything and address immediately
  • high: Address as soon as current task completes
  • normal: Handle in normal workflow
  • low: Handle when you have free time

Best Practices

1. Push Notifications (Automatic)

As of v0.18.10, AI Maestro uses push notifications to instantly alert agents when messages arrive:

[MESSAGE] From: backend-api@mini-lola - API endpoint ready - check your inbox

No polling or manual checking required - agents receive notifications in real-time via tmux.

To check for any missed messages (e.g., at session startup):

# Quick check for unread messages
amp-inbox

2. Use Clear Subjects

Good: "Need POST /api/users endpoint with pagination" Bad: "Help needed"

3. Provide Context

Always include:

  • What you need
  • Why you need it
  • Any relevant code/files
  • Expected format/structure

4. Respond to Requests

If you receive a request-type message, always send a response when done.

5. Clean Up Old Messages

Delete messages after handling:

# Delete a specific message
amp-delete <message-id>

# Or use the delete tool directly
rm ~/.agent-messaging/messages/inbox/<message-id>.json

Troubleshooting

Messages Not Appearing

  1. Check AMP status: amp-status
  2. Verify agent is initialized: ls ~/.agent-messaging/config.json
  3. Check message files: ls ~/.agent-messaging/messages/inbox/
  4. Verify session name: tmux display-message -p '#S'

Agent Not Finding Messages

  1. Ensure agent is initialized: amp-init --auto
  2. Check directory exists: ls ~/.agent-messaging/messages/inbox/
  3. Verify file permissions: chmod -R u+rw ~/.agent-messaging/

Message JSON Format Errors

Use this template and replace values:

{
  "id": "msg-TIMESTAMP-RANDOM",
  "from": "sender-session-name",
  "to": "recipient-session-name",
  "timestamp": "2025-01-11T14:30:00Z",
  "subject": "Your subject",
  "priority": "normal",
  "status": "unread",
  "content": {
    "type": "request",
    "message": "Your message here"
  }
}

Advanced: Custom Message Handlers

You can create custom scripts that automatically process messages using the AMP CLI:

#!/bin/bash
# ~/.local/bin/process-agent-messages.sh

INBOX=~/.agent-messaging/messages/inbox

for msg_file in $INBOX/*.json; do
  [ -f "$msg_file" ] || continue

  # Parse message envelope and payload
  PRIORITY=$(jq -r '.envelope.priority' "$msg_file")
  SUBJECT=$(jq -r '.envelope.subject' "$msg_file")
  FROM=$(jq -r '.envelope.from' "$msg_file")

  # Handle based on priority
  if [ "$PRIORITY" = "urgent" ]; then
    echo "🚨 URGENT MESSAGE from $FROM: $SUBJECT"
    # Trigger notification, log, etc.
  fi
done

Or use the AMP API to fetch and process messages programmatically.

Learn more: Visit agentmessaging.org for the full AMP protocol specification.

Integration with Claude Code

Push Notifications (v0.18.10+)

AI Maestro automatically delivers messages via push notifications. When a message arrives, you'll see:

[MESSAGE] From: backend-api - API endpoint ready - check your inbox

Add to your CLAUDE.md project instructions:

## Inter-Agent Communication

This project uses the AI Maestro messaging system for agent coordination.

**When you receive a message notification:**
1. Run `amp-inbox` to see your inbox
2. Read messages with `amp-read <msg-id>`
3. Prioritize urgent/high priority messages
4. Incorporate message context into your task planning

**When you need help from another agent:**
1. Identify the appropriate specialist agent
2. Use `amp-send <agent> <subject> <message>` or the Messages tab in the dashboard
3. Include clear context and requirements
4. Continue with independent work while waiting for response

**When you complete work requested by another agent:**
1. Send a response message with results
2. Include file paths, line numbers, and any relevant details
3. Mark the original request as handled

Slack Integration

Connect your team's Slack workspace to AI Maestro agents using the AI Maestro Slack Bridge.

How It Works

Slack Message → Slack Bridge → AI Maestro API → Agent Inbox
                                                      ↓
Slack Thread  ← Slack Bridge ← AI Maestro API ← Agent Response

Usage

DM the bot: Send a direct message to the AI Maestro bot in Slack.

Mention in channels:

@AI Maestro what's the status of the API refactoring?

Route to specific agents:

@AIM:backend-api check the server health
@AIM:frontend-dev review the CSS changes
@AIM:graph-query find all API endpoints

Responding to Slack Messages

When you receive a notification from Slack:

[MESSAGE] From: slack-bot - Slack: Question from Juan - check your inbox
  1. Check your inbox: amp-inbox
  2. Read the message to see the full Slack context
  3. Send your response to slack-bot - it will be posted to the Slack thread
amp-send slack-bot \
  "Re: Question from Juan" \
  "The API endpoint is at /api/users. See routes/users.ts for implementation." \
  normal response

Setup

See the AI Maestro Slack Bridge repository for installation and configuration.

Future Enhancements

Potential future features for the messaging system:

  • Message Templates: Pre-defined message formats for common scenarios
  • Auto-Responses: Agents automatically acknowledge receipt
  • Message Threading: Link related messages together
  • Rich Content: Attach files, code snippets, screenshots
  • Message Search: Full-text search across all messages
  • Webhooks: Trigger external actions on message receipt
  • Analytics: Track agent communication patterns

AMP Federation with External Providers

AI Maestro can federate with external AMP providers, allowing your agents to communicate with agents on other networks.

Register with an External Provider

# Register with CrabMail (example)
amp-register --provider https://crabmail.ai --tenant myorg

# Register with another AI Maestro instance
amp-register --provider http://192.168.1.10:23000 --tenant remote

Send Messages to External Agents

# Send to an agent on CrabMail
amp-send alice@acme.crabmail.ai "Hello" "Cross-network message!"

# Send to an agent on another AI Maestro instance
amp-send backend@remote.aimaestro.local "Request" "Can you help?"

Fetch Messages from External Providers

# Fetch pending messages from all registered providers
amp-fetch

Learn more about federation: See the AMP Protocol Specification for details on cross-network messaging.