comeonoliver/skillshub/ai-maestro-agent-messaging

AI Maestro Agent Messaging

Purpose

Enable communication between AI coding agents using AI Maestro's dual-channel messaging system. Agents are identified by their agent ID or alias, with tmux session names as a fallback. Supports both SENDING and RECEIVING messages.

CRITICAL: Inter-Agent Communication

YOU ARE AN AGENT - This skill is for agent-to-agent communication, NOT human-agent communication.

IMPORTANT: Understanding "Your Messages"

When the human operator says "check your messages" or "read your messages":

• YOUR inbox = Messages addressed TO YOUR AGENT (from anyone - operator, other agents, etc.)
• NOT the operator's inbox = You check YOUR inbox, not the operator's

Example:

• Human says: "Check your messages"
• You are agent: backend-api
• You check: ~/.aimaestro/messages/inbox/backend-api/ (YOUR inbox)
• These are messages addressed TO backend-api (from any sender)
• You DO NOT check: The operator's inbox or any other agent's inbox

Agent Identity

• Your inbox = Messages addressed TO YOUR AGENT (from any sender)
• Your agent ID = Unique identifier for this agent (can also use agent name as fallback)
• Your agent name = The tmux session you're running in (get with tmux display-message -p '#S')
• Your inbox location = ~/.aimaestro/messages/inbox/YOUR-AGENT-ID/ or ~/.aimaestro/messages/inbox/YOUR-AGENT-NAME/

You do NOT read:

• ❌ The operator's inbox
• ❌ Other agents' inboxes
• ❌ Messages not addressed to your agent

You DO read:

• ✅ Messages addressed TO YOUR AGENT
• ✅ YOUR OWN inbox only
• ✅ Your agent's inbox: ~/.aimaestro/messages/inbox/YOUR-AGENT-ID/

When to Use This Skill

Sending (Agent-to-Agent):

• User (operator) says "send a message to [another-agent]"
• User says "notify [another-agent]" or "alert [another-agent]"
• User wants YOU to communicate with ANOTHER agent
• You need to send urgent alerts or requests to OTHER AGENTS

Receiving (Check YOUR OWN Inbox):

• User says "check my inbox" or "check my messages" = Use check-aimaestro-messages.sh
• User says "read my messages" or "read message X" = Use read-aimaestro-message.sh <id>
• User asks "any new messages?" = Use check-aimaestro-messages.sh
• Agent just started (best practice: check YOUR inbox first)
• You want to see what OTHER AGENTS have sent TO YOU

RECOMMENDED WORKFLOW:

1. First check for unread messages: check-aimaestro-messages.sh
2. Then read specific message: read-aimaestro-message.sh <message-id>
3. Message is automatically marked as read after reading

Available Tools

PART 1: RECEIVING MESSAGES (YOUR OWN INBOX)

📖 QUICK START - Check and Read Messages:

# Step 1: Check what unread messages you have
check-aimaestro-messages.sh
 
# Output shows:
# [msg-1234...] 🔴 From: backend-api | 2025-10-29 14:30
#     Subject: Authentication endpoint ready
#     Preview: The /api/auth/login endpoint is now...
 
# Step 2: Read the specific message (automatically marks as read)
read-aimaestro-message.sh msg-1234...
 
# Step 3: Check again - that message is now gone from unread
check-aimaestro-messages.sh
# Output: "📭 No unread messages"

⚠️ CRITICAL: What "YOUR inbox" means:

• YOU = The AI agent running in this tmux session
• YOUR inbox = ~/.aimaestro/messages/inbox/YOUR-AGENT-ID/ (or agent name as fallback)
• Messages in YOUR inbox = Messages OTHER AGENTS sent TO YOU
• NOT the operator's messages, NOT other agents' private messages

IMPORTANT: These commands check YOUR AGENT'S inbox only. They automatically:

1. Detect your current agent ID or agent name
2. Read from ~/.aimaestro/messages/inbox/YOUR-AGENT-ID/
3. Show messages that OTHER AGENTS sent TO YOU
4. Do NOT access anyone else's inbox

1. Check YOUR Inbox for UNREAD Messages (Recommended)

Command:

check-aimaestro-messages.sh [--mark-read]

What it does:

• Shows ONLY UNREAD messages in YOUR inbox (messages sent TO YOUR AGENT)
• Automatically detects YOUR agent's session
• Displays: priority indicator, sender, subject, preview, timestamp
• Optional --mark-read flag to mark all messages as read after viewing
• This is the recommended way to check messages - avoids re-reading old messages

Example:

# Check unread messages without marking as read
check-aimaestro-messages.sh
 
# Check and mark all as read
check-aimaestro-messages.sh --mark-read

Output format:

📬 You have 3 unread message(s)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
[msg-167...] 🔴 From: backend-architect | 2025-10-29 13:45
    Subject: API endpoint ready
    Preview: The POST /api/auth/login endpoint is now...
 
[msg-168...] 🔵 From: frontend-dev | 2025-10-29 14:20
    Subject: Need help with styling
    Preview: Can you review the CSS for the navigation...

2. Read Specific Message and Mark as Read

Command:

read-aimaestro-message.sh <message-id> [--no-mark-read]

What it does:

• Retrieves and displays the full message content
• Automatically marks the message as read (unless --no-mark-read flag)
• Shows all message details: content, context, forwarding info
• Perfect for reading a specific message after checking the list

Example:

# Read message (automatically marks as read)
read-aimaestro-message.sh msg-1234567890-abc
 
# Peek at message without marking as read
read-aimaestro-message.sh msg-1234567890-abc --no-mark-read

Output format:

═══════════════════════════════════════════════════════════════
📧 Message: API endpoint ready
═══════════════════════════════════════════════════════════════
 
From:     backend-architect
To:       frontend-dev
Date:     2025-10-29 13:45:00
Priority: 🔴 urgent
Type:     response
 
───────────────────────────────────────────────────────────────
 
The POST /api/auth/login endpoint is now deployed and ready...
 
───────────────────────────────────────────────────────────────
📎 Context:
{
  "endpoint": "/api/auth/login"
}
 
✅ Message marked as read
═══════════════════════════════════════════════════════════════

3. Auto-Display on Agent Start (Legacy - DO NOT USE MANUALLY)

Command:

check-and-show-messages.sh

What it does:

• Automatically runs when you attach to a tmux session
• Shows a summary of unread messages
• DO NOT run this command manually - it's for auto-display only
• For manual checking, use `check-aimaestro-messages.sh` instead

Why not use this manually?

• It's designed for auto-display (runs on tmux attach)
• Output format is optimized for quick glance, not interactive reading
• Use the new commands (#1 and #2 above) for better experience

Output format:

Message: msg_1234567890_abcde
From: backend-architect          ← Another agent sent this TO YOU
To: frontend-dev                 ← YOUR session name
Subject: Need API endpoint
Priority: high
Type: request
Status: unread
Timestamp: 2025-01-17 14:23:45
Content: Please implement POST /api/users with pagination...

4. Check for New Messages Count (Quick)

Command:

check-new-messages-arrived.sh

What it does:

• Shows count of unread messages in YOUR inbox
• Automatically checks YOUR session's inbox
• Quick check without full details
• Returns "No new messages" or "You have X new message(s)"

Example:

check-new-messages-arrived.sh
# Output: "You have 3 new message(s)"  ← Messages sent TO YOU

5. Read Specific Message FROM YOUR Inbox (Direct File Access - Advanced)

Command:

cat ~/.aimaestro/messages/inbox/$(tmux display-message -p '#S')/<message-id>.json | jq

What it does:

• Read a specific message file from YOUR inbox
• $(tmux display-message -p '#S') = YOUR session name (auto-detected)
• Use jq for pretty formatting
• Useful when you know the message ID

Directory structure:

~/.aimaestro/messages/
├── inbox/YOUR-SESSION-NAME/     # Messages TO YOU from other agents
│   └── msg_*.json
├── sent/YOUR-SESSION-NAME/      # Messages FROM YOU to other agents
│   └── msg_*.json
└── archived/YOUR-SESSION-NAME/  # YOUR archived messages
    └── msg_*.json

Example:

# Get YOUR session name
tmux display-message -p '#S'
# Output: frontend-dev  ← This is YOU
 
# List all messages in YOUR inbox
ls ~/.aimaestro/messages/inbox/$(tmux display-message -p '#S')/
 
# Read specific message sent TO YOU
cat ~/.aimaestro/messages/inbox/$(tmux display-message -p '#S')/msg_1234567890_abcde.json | jq

4. Mark Message as Read (via API)

Command:

# Get current session name
SESSION_NAME=$(tmux display-message -p '#S')
 
# Mark message as read
curl -X PATCH "http://localhost:23000/api/messages?agent=$SESSION_NAME&id=<message-id>&action=read" \
  -H 'Content-Type: application/json'

PART 2: SENDING MESSAGES (TO OTHER AGENTS)

⚠️ CRITICAL: What "sending a message" means:

• Operator tells YOU to send a message TO ANOTHER AGENT
• NOT sending messages to the operator
• Message goes to ANOTHER AGENT's inbox
• Target = Another agent (identified by their tmux session name)

5. File-Based Messages (Persistent, Structured)

Use for detailed, non-urgent communication that needs to be referenced later BY OTHER AGENTS.

Command:

send-aimaestro-message.sh <to_agent[@host]> <subject> <message> [priority] [type]

Parameters:

• to_agent[@host] (required) - Target agent with optional host:
• backend-api - Send to agent on same host (local)
• backend-api@mac-mini - Send to agent on remote host "mac-mini"
• backend-api@local - Explicitly send to local agent
• subject (required) - Brief subject line
• message (required) - Message content to send TO OTHER AGENT
• priority (optional) - low | normal | high | urgent (default: normal)
• type (optional) - request | response | notification | update (default: request)

Examples:

# Simple request (local agent)
send-aimaestro-message.sh backend-architect "Need API endpoint" "Please implement POST /api/users with pagination"
 
# Cross-host message (agent on remote machine)
send-aimaestro-message.sh crm-api@mac-mini "Customer data sync" "Please sync customer records from CRM" high request
 
# Urgent notification (local)
send-aimaestro-message.sh frontend-dev "Production issue" "API returning 500 errors" urgent notification
 
# Response to request
send-aimaestro-message.sh orchestrator "Re: Task complete" "User dashboard finished at components/Dashboard.tsx" normal response
 
# Progress update
send-aimaestro-message.sh project-lead "Payment integration: 60% done" "Stripe API integrated. Working on webhooks. ETA: 2 hours." normal update

PART 2.5: CROSS-HOST MESSAGING

AI Maestro supports sending messages to agents running on different machines (hosts). This enables distributed agent workflows across your infrastructure.

Host Configuration

Hosts are configured in ~/.aimaestro/hosts.json:

{
  "hosts": [
    {
      "id": "local",
      "name": "macbook-pro",
      "url": "http://localhost:23000",
      "type": "local",
      "enabled": true
    },
    {
      "id": "mac-mini",
      "name": "mac-mini-server",
      "url": "http://100.80.12.6:23000",
      "type": "remote",
      "enabled": true
    }
  ]
}

Addressing Agents on Remote Hosts

Use the agent@host format to send messages to remote agents:

# Send to agent "crm-api" on host "mac-mini"
send-aimaestro-message.sh crm-api@mac-mini "Sync request" "Please sync customer data"
 
# Send to agent "data-processor" on host "cloud-server"
send-aimaestro-message.sh data-processor@cloud-server "Process batch" "Run nightly ETL" high request

How Cross-Host Messaging Works