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 from the agent registry. 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 - AUTOMATIC, DO NOT SET MANUALLY

Your identity is detected automatically. Just use the messaging scripts - they handle everything.

• Your inbox = Messages addressed TO YOUR AGENT
• Your agent alias = Your name (e.g., backend-api, lola, crm)
• Your inbox location = Handled automatically by the scripts

DO NOT:

• ❌ Set environment variables manually
• ❌ Prefix messages with your agent ID
• ❌ Try to configure your identity

JUST DO:

• ✅ Run check-aimaestro-messages.sh to check your inbox
• ✅ Run send-aimaestro-message.sh <target> <subject> <message> to send
• ✅ Run reply-aimaestro-message.sh <msg-id> <reply> to reply

The scripts detect who you are automatically from your tmux session or working directory.

ONLY FOR EXTERNAL AGENTS (Skip if you're in AI Maestro)

⚠️ READ THIS FIRST: If you are running inside AI Maestro (in a tmux session managed by the dashboard), SKIP THIS SECTION. Your identity is automatic. The section below is ONLY for agents running OUTSIDE of AI Maestro.

What is an "External Agent"?

• An agent running in a separate Claude Code instance (not managed by AI Maestro)
• An agent in CI/CD pipelines
• An agent on a machine without AI Maestro installed
• NOT you, if you see tmux sessions in the AI Maestro dashboard

For External Agents ONLY:

# Set identity ONLY if you're external (not in AI Maestro)
export AI_MAESTRO_AGENT_ID="my-project"
export AI_MAESTRO_HOST_ID="my-hostname"  # Optional

# Then use messaging normally
send-aimaestro-message.sh lola@mini-lola "Hello" "Message from external"
check-aimaestro-messages.sh

How to know if you're external:

• You DON'T see yourself in the AI Maestro dashboard
• You're NOT in a tmux session named after an agent
• You're running from a random directory, not an agent's workingDirectory

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 Messages (Push Notifications):

• You receive automatic notifications when messages arrive - no polling needed!
• Notification format: [MESSAGE] From: sender - Subject - check your inbox
• When you see a notification, use check-aimaestro-messages.sh to see details
• Use read-aimaestro-message.sh <id> to read the full message
• User asks "any new messages?" = Use check-aimaestro-messages.sh

RECOMMENDED WORKFLOW:

1. Receive notification: [MESSAGE] From: slack-bridge - Question from #engineering - check your inbox
2. Check inbox details: check-aimaestro-messages.sh
3. Read specific message: read-aimaestro-message.sh <message-id>
4. Message is automatically marked as read after reading
5. Reply if needed: reply-aimaestro-message.sh <message-id> "Your reply"
   • For Slack messages (📱), reply automatically posts to Slack thread

Note: Notifications are instant - you don't need to poll or periodically check for messages.

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 with your current identity (from env var, tmux, or git repo)
• YOUR inbox = ~/.aimaestro/messages/inbox/YOUR-AGENT-ID/
• 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. Reply to a Message

Command:

reply-aimaestro-message.sh <message-id> <reply-message> [priority]

What it does:

• Replies to a specific message in your inbox
• Automatically addresses the reply to the original sender
• Sets inReplyTo field linking to the original message
• If original message came from Slack, reply is posted to Slack thread
• Subject is automatically prefixed with "Re: "

Parameters:

• message-id (required) - The message ID to reply to
• reply-message (required) - Your reply content
• priority (optional) - low | normal | high | urgent (default: normal)

Examples:

# Simple reply
reply-aimaestro-message.sh msg-1234567890-abc "Thanks, I'll look into it"

# Urgent reply
reply-aimaestro-message.sh msg-1234567890-abc "Found the bug - deploying fix now" urgent

# Reply to Slack message (automatically posts to Slack thread)
reply-aimaestro-message.sh msg-slack-abc "The API is ready, you can start integration"

Output format:

Reply sent
   From: backend-api@hostname
   To: frontend-dev@hostname
   Subject: Re: Need API endpoint
   Slack: Will post to channel CS5SXB7C6  # Only shown for Slack messages

4. Auto-Display on Agent Start (DEPRECATED)

Command:

check-and-show-messages.sh

⚠️ DEPRECATED: This command is no longer needed. AI Maestro now uses push notifications to alert you instantly when messages arrive. You don't need to poll or auto-check on startup.

What it did (legacy):

• Automatically ran when you attach to a tmux session
• Showed a summary of unread messages

What to use instead:

• Push notifications alert you automatically when messages arrive
• Use check-aimaestro-messages.sh when you want to check inbox manually
• Use read-aimaestro-message.sh <id> to read specific messages

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)

NOTE: Prefer using read-aimaestro-message.sh instead - it handles everything automatically.

Command (if needed):

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

Directory structure:

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

4. Mark Message as Read (via API)

Command:

# Get current session name
SESSION_NAME=$(tmux display-message -p '#S')

# Get the API URL (from identity endpoint or use hostname)
API_URL=$(curl -s http://127.0.0.1:23000/api/hosts/identity | jq -r '.host.url // empty')
[ -z "$API_URL" ] && API_URL="http://$(hostname | tr '[:upper:]' '[:lower:]'):23000"

# Mark message as read
curl -X PATCH "${API_URL}/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 agent ID or alias from the registry)

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 (host is optional thanks to smart lookup):
  • backend-api - Script automatically searches ALL hosts to find this agent
  • api-form - Fuzzy matching: finds api-forms even with typos/partial names
  • backend-api@mac-mini - Explicitly specify host (skips search, faster)
• subject (required) - Brief subject line
• message (required) - Message content to send TO OTHER AGENT
• priority (optional) - low | normal | high | urgent (default: normal)

Smart Lookup (v0.17.32+): When no @host is specified, the script automatically:

1. Searches ALL enabled hosts for the agent
2. If found on exactly 1 host → sends automatically
3. If found on multiple hosts → asks which one you meant
4. If not found → tries fuzzy/partial matching

Fuzzy Matching (v0.17.33+): If exact name not found, searches for partial matches:

• api-form → finds api-forms (typo tolerance)
• forms → finds 23blocks-api-forms (partial name)
• Single fuzzy match: shows 🔍 Found partial match: ... then sends
• Multiple fuzzy matches: shows options for clarification
• type (optional) - request | response | notification | update (default: request)

Examples:

# Simple request - smart lookup finds agent automatically
send-aimaestro-message.sh backend-architect "Need API endpoint" "Please implement POST /api/users with pagination"

# Works with partial names - fuzzy matching finds the right agent
send-aimaestro-message.sh api-form "Customer data sync" "Please sync customer records"
# Output: 🔍 Found partial match: api-forms@hostname
# ✅ Message sent

# Explicit host (faster - skips search)
send-aimaestro-message.sh crm-api@mac-mini "Customer data sync" "Please sync customer records from CRM" high request

# Urgent notification
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. The id should be the machine's hostname (not "local"):

{
  "hosts": [
    {
      "id": "macbook-pro.local",
      "name": "MacBook Pro",
      "url": "http://100.104.178.57:23000",
      "type": "local",
      "enabled": true,
      "description": "This machine"
    },
    {
      "id": "mac-mini.local",
      "name": "Mac Mini Server",
      "url": "http://100.80.12.6:23000",
      "type": "remote",
      "enabled": true,
      "description": "Mac Mini via Tailscale"
    }
  ]
}

Important:

• The id should be the actual hostname, NOT "local"
• The url should be the machine's network IP (preferably Tailscale IP for mesh networking), NOT localhost
• Use type: "local" only for THIS machine's entry

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

With explicit host (agent@host):

1. Parse destination and look up host URL from ~/.aimaestro/hosts.json
2. Query that specific host's API to resolve agent
3. Send message to that host's /api/messages endpoint

Without host (smart lookup):

1. Search ALL enabled hosts for the agent (exact match first)
2. If not found exactly, try fuzzy/partial matching on all hosts
3. Single match → auto-select that host and send
4. Multiple matches → prompt for clarification
5. No matches → show helpful error with available hosts

Message Display with Hosts

When viewing messages, sender info includes their host:

From: backend-api@macbook-pro
To: crm-api@mac-mini
Subject: Data sync complete

Troubleshooting Cross-Host Messaging

Cannot find host:

# List available hosts
source ~/.local/share/aimaestro/shell-helpers/common.sh
list_hosts

Remote host unreachable:

• Check host URL in ~/.aimaestro/hosts.json
• Verify network connectivity: curl http://<host-url>/api/hosts/identity
• Ensure AI Maestro is running on remote host

Agent not found on remote host:

• Verify agent exists on remote: curl http://<host-url>/api/agents | jq '.agents[].alias'
• Check agent alias spelling

PART 2.6: SLACK INTEGRATION (BRIDGED MESSAGES)

AI Maestro supports receiving messages from Slack via the AI Maestro Slack Bridge. When someone mentions or messages you on Slack, the message appears in your inbox with Slack context attached.

Setup: See the Slack Bridge repository for installation and configuration.

How Slack Bridged Messages Work

1. Receiving from Slack:

   • A Slack bridge service monitors for messages directed to agents
   • Messages are converted to AI Maestro format with Slack context attached
   • The message appears in your inbox with a 📱 indicator

2. Slack Context Fields: When a message comes from Slack, it includes:

   • content.slack.channel - The Slack channel ID
   • content.slack.thread_ts - The thread timestamp (for threading replies)
   • content.slack.user - The Slack user ID who sent the message

Identifying Slack Messages

In check-aimaestro-messages.sh:

[msg-1234...] 🔴 📱 From: slack-bridge | 2025-01-23 14:30
    Subject: Question from #engineering
    Preview: Can you help with the API design? [via Slack]

• 📱 emoji indicates the message came from Slack
• [via Slack] tag on the preview line

In read-aimaestro-message.sh:

═══════════════════════════════════════════════════════════════
📧 Message: Question from #engineering
═══════════════════════════════════════════════════════════════

From:     slack-bridge
To:       backend-api
Date:     2025-01-23 14:30:00
Priority: 🔵 normal
Type:     request

───────────────────────────────────────────────────────────────

Can you help with the API design for the new user service?

───────────────────────────────────────────────────────────────
📱 VIA SLACK:

   Channel:  CS5SXB7C6
   Thread:   1769217994.223089
   User:     US37DSBS8

═══════════════════════════════════════════════════════════════
✅ Message marked as read

💡 To reply (will post to Slack thread):
   reply-aimaestro-message.sh msg-1234... "Your reply here"
═══════════════════════════════════════════════════════════════

Replying to Slack Messages

When you reply to a message that came from Slack, your reply is automatically posted to the same Slack thread:

# Reply to a Slack-bridged message
reply-aimaestro-message.sh msg-1234567890-abc "I can help! The API design should use REST with..."

# Output:
# Replying to Slack thread...
# ✅ Reply sent
#    From: backend-api@hostname
#    To: slack-bridge
#    Subject: Re: Question from #engineering
#    Slack: Will post to channel CS5SXB7C6

How it works:

1. reply-aimaestro-message.sh fetches the original message
2. If content.slack exists, it's automatically included in the reply
3. The Slack bridge picks up the reply and posts it to the original thread
4. The Slack user sees your response in-context

Scenario: Responding to Slack Questions

# 1. Check your inbox - notice the 📱 Slack indicator
check-aimaestro-messages.sh

# Output:
# [msg-abc123...] 🔵 📱 From: slack-bridge | 2025-01-23 15:00
#     Subject: Help with database schema
#     Preview: @backend-api Can you review the new schema? [via Slack]

# 2. Read the full message to see Slack context
read-aimaestro-message.sh msg-abc123...

# Shows VIA SLACK section with channel, thread, user info

# 3. Reply - it will automatically post to Slack thread
reply-aimaestro-message.sh msg-abc123... "Reviewed the schema. Looks good, but consider adding an index on user_id for better query performance."

# Your reply appears in the Slack thread!

PART 2.7: RECEIVING PUSH NOTIFICATIONS

AI Maestro uses push notifications to alert you when messages arrive. This eliminates the need for polling - you're notified instantly when someone sends you a message.

How Notifications Work

When a message is delivered to your inbox, AI Maestro automatically sends a notification to your terminal:

[MESSAGE] From: slack-bridge - Question from #engineering - check your inbox

Notification format:

• [MESSAGE] - Indicates an incoming message notification
• From: <sender> - Who sent the message (agent name or slack-bridge for Slack)
• <subject> - The message subject
• Priority indicators: 🔴 [URGENT] or 🟠 [HIGH] for urgent/high priority messages

Responding to Notifications

When you see a notification:

1. Check your inbox to see the message details:

   check-aimaestro-messages.sh
   

2. Read the full message:

   read-aimaestro-message.sh <message-id>
   

3. Reply (works for both agent and Slack messages):

   reply-aimaestro-message.sh <message-id> "Your response here"
   

Why Push Notifications?

• Instant delivery - No delay waiting for polling intervals
• Zero overhead - No background processes polling for messages
• Non-intrusive - Notifications appear without interrupting your work
• Reliable - Notifications are sent at message delivery time, guaranteed

Note: You still use check-aimaestro-messages.sh and read-aimaestro-message.sh to read messages - notifications just tell you when they arrive.

6. Instant Notifications (Real-time, Ephemeral)

Use for urgent alerts that need immediate attention FROM OTHER AGENTS.

Command:

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

Parameters:

• target_session (required) - Target agent's name (ANOTHER AGENT, not operator)
• message (required) - Alert text to send TO OTHER AGENT
• method (optional) - display | inject | echo (default: display)

Methods:

• display - Popup notification (non-intrusive, auto-dismisses)
• inject - Inject into terminal history (visible but interrupts)
• echo - Formatted output (most visible, most intrusive)

Examples:

# Quick alert (popup)
send-tmux-message.sh backend-architect "Check your inbox!"

# Urgent visible alert
send-tmux-message.sh frontend-dev "Build failed! Check logs" inject

# Critical formatted alert
send-tmux-message.sh backend-architect "PRODUCTION DOWN!" echo

7. Combined Approach (Urgent + Detailed)

For critical issues, use both methods:

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

# 2. Provide full details
send-aimaestro-message.sh backend-architect \
  "Production: Database timeout" \
  "All /api/users endpoints failing since 14:30. Connection pool exhausted. ~200 users affected. Need immediate fix." \
  urgent \
  notification

Decision Guide

Use file-based (send-aimaestro-message.sh) when:

• Message contains detailed requirements or context
• Recipient needs to reference it later
• Communication is structured (priority, type)
• Not time-critical (within hours)

Use instant (send-tmux-message.sh) when:

• Urgent attention needed (minutes)
• Quick FYI ("build done", "tests passing")
• Making sure file message gets seen
• Production emergency

Use both when:

• Critical AND detailed information needed
• Blocking another agent's work
• Production issues affecting users

Message Type Guidelines

• request - Need someone to do something (implement, review, help)
• response - Answering a request (task complete, here's the result)
• notification - FYI update, no action needed (deploy done, tests passing)
• update - Progress report on ongoing work (50% complete, ETA 2 hours)

Priority Guidelines

• urgent - Production down, data loss, security issue (respond in < 15 min)
• high - Blocking work, important feature needed soon (respond in < 1 hour)
• normal - Standard workflow (respond within 4 hours)
• low - Nice-to-have, when free time available

Examples by Scenario

RECEIVING Examples (Checking YOUR OWN Inbox)

Scenario R1: Responding to Message Notifications

# YOU are agent "frontend-dev"
# You receive a notification:
# [MESSAGE] From: backend-api - API endpoint ready - check your inbox

# 1. Check your inbox to see the message
check-aimaestro-messages.sh

# 2. Read the specific message
read-aimaestro-message.sh msg-1234567890-abc

# 3. Reply if needed
reply-aimaestro-message.sh msg-1234567890-abc "Thanks! I'll integrate it now."

Scenario R2: Operator Asks About Messages

# Operator asks: "Any new messages?"
# YOU (the agent) check YOUR inbox

check-aimaestro-messages.sh
# Output shows unread messages:
# [msg-123...] 🔵 From: backend-api | 2025-01-23 14:30
#     Subject: API endpoint ready
#     Preview: The POST /api/users endpoint is now...

# Note: With push notifications, you'll already know about messages
# because AI Maestro notifies you when they arrive!

Scenario R3: Read Message and Respond

# YOU are agent "backend-architect"
# You received notification: [MESSAGE] From: frontend-dev - Need API endpoint - check your inbox

# 1. Check YOUR inbox for details
check-aimaestro-messages.sh

# Output shows:
# [msg-1705502625...] 🟠 From: frontend-dev | 2025-01-17 14:23
#     Subject: Need API endpoint
#     Preview: Please implement POST /api/users with pagination...

# 2. Read full message
read-aimaestro-message.sh msg-1705502625-abc123

# 3. Work on the request (implement the feature)

# 4. Reply TO THE AGENT who messaged you
reply-aimaestro-message.sh msg-1705502625-abc123 \
  "Implemented POST /api/users at routes/users.ts:45. Includes pagination support."

Scenario R4: Handle Urgent Message

# YOU are agent "frontend-dev"
# You receive URGENT notification:
# 🔴 [URGENT] [MESSAGE] From: backend-architect - Production: Database down - check your inbox

# 1. Check inbox immediately
check-aimaestro-messages.sh

# Output shows:
# [msg-urgent...] 🔴 From: backend-architect | 2025-01-23 15:30
#     Subject: Production: Database down
#     Preview: All queries failing since 15:30...

# 2. Read full details
read-aimaestro-message.sh msg-urgent-abc123

# 3. Acknowledge and work on issue
reply-aimaestro-message.sh msg-urgent-abc123 "Investigating now!"

# 4. After resolving, send detailed update
reply-aimaestro-message.sh msg-urgent-abc123 \
  "RESOLVED: Issue was connection pool exhaustion. Increased max_connections. System stable."

Scenario R5: Receive and Reply to Slack Message

# YOU are agent "backend-api"
# 1. Check YOUR inbox - notice the 📱 Slack indicator
check-aimaestro-messages.sh

# Output shows Slack-bridged message:
# [msg-slack-123...] 🔵 📱 From: slack-bridge | 2025-01-23 10:30
#     Subject: Question from #engineering
#     Preview: @backend-api What's the status of the auth API? [via Slack]

# 2. Read full message to see Slack context
read-aimaestro-message.sh msg-slack-123...

# Shows:
# 📱 VIA SLACK:
#    Channel:  C0123ENGG
#    Thread:   1737641400.123456
#    User:     U0456USER

# 3. Reply - it automatically posts to Slack thread
reply-aimaestro-message.sh msg-slack-123... "The auth API is 80% complete. Login and registration are done, working on password reset. ETA: tomorrow."

# Your reply appears in the Slack #engineering thread!

SENDING Examples

Scenario S1: Request Work from Another Agent

send-aimaestro-message.sh backend-api \
  "Need GET /api/users endpoint" \
  "Building user list UI. Need endpoint returning array of users with {id, name, email}. Pagination optional but nice." \
  high \
  request

Scenario S2: Urgent Alert

# Get attention
send-tmux-message.sh backend-api "🚨 Urgent: Check inbox!"

# Provide details
send-aimaestro-message.sh backend-api \
  "Production: API failing" \
  "All /users endpoints returning 500. Database connection timeout. ~100 users affected." \
  urgent \
  notification

Scenario S3: Progress Update

send-aimaestro-message.sh project-lead \
  "User auth: 75% complete" \
  "✅ Database schema done
✅ Registration endpoint done
✅ Login endpoint done
⏳ Password reset in progress

ETA: 1 hour. No blockers." \
  normal \
  update

Scenario S4: Reply to Request

send-aimaestro-message.sh frontend-dev \
  "Re: GET /api/users endpoint" \
  "Endpoint ready at routes/users.ts:120. Returns {users: Array<User>, total: number, page: number}. Supports pagination with ?page=1&limit=20." \
  normal \
  response

Workflow

Receiving Messages Workflow (Push Notifications)

You receive automatic notifications when messages arrive - no polling needed!

1. Receive notification - AI Maestro automatically notifies you when a message arrives:

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

   • Notifications appear instantly when messages are delivered
   • No need to poll or periodically check

2. Check your inbox - Run check-aimaestro-messages.sh to see message details:

   check-aimaestro-messages.sh
   

   • Shows unread messages in YOUR inbox
   • Displays: sender, subject, preview, priority

3. Read full message - Use read-aimaestro-message.sh to see complete content:

   read-aimaestro-message.sh <message-id>
   

   • Automatically marks message as read
   • Shows full content, context, and Slack info if applicable

4. Assess urgency - Check priority level (urgent = respond immediately)

5. Take action - Work on the request

   • Investigate issue
   • Implement feature
   • Or acknowledge receipt

6. Reply - Use reply-aimaestro-message.sh to respond:

   reply-aimaestro-message.sh <message-id> "Your response"
   

   • Automatically addresses reply to original sender
   • For Slack messages, posts to the Slack thread

Sending Messages Workflow (TO Other Agents)

Remember: Operator tells YOU to send a message TO ANOTHER AGENT

1. Understand the request - What does the operator want YOU to communicate TO ANOTHER AGENT?

2. Identify target agent - Which OTHER agent should receive this message FROM YOU?

   • Target = Another agent's name
   • NOT the operator
   • NOT your own inbox

3. Choose method - Urgent? Use instant. Detailed? Use file-based. Both? Use both.

   • File-based: Goes to OTHER AGENT's inbox
   • Instant: Popup in OTHER AGENT's terminal

4. Select priority - How urgent is this for THE OTHER AGENT?

5. Choose type - Is it a request, response, notification, or update TO THE OTHER AGENT?

6. Execute command - Run the appropriate send-* script

   • Sends FROM YOU TO OTHER AGENT
   • Message appears in OTHER AGENT's inbox

7. Confirm - Tell operator: "Message sent to [other-agent-name]"

Error Handling

Receiving Errors (Checking YOUR Inbox)

No messages found:

• This is normal if YOUR inbox is empty
• Output: "No messages in your inbox"
• Means: No other agents have sent messages TO YOU yet

Script not found:

• Check PATH: which check-and-show-messages.sh
• Verify scripts installed: ls -la ~/.local/bin/check-*.sh

Cannot read inbox directory:

• Check YOUR inbox directory exists: ls -la ~/.aimaestro/messages/inbox/$(tmux display-message -p '#S')/
• Verify YOUR session name: tmux display-message -p '#S'
• Remember: You're reading YOUR inbox, not someone else's

Important: If you can't find messages:

• Make sure you're checking the RIGHT inbox (yours)
• Don't try to read other agents' inboxes
• Don't try to read the operator's messages

Sending Errors

Command fails:

• Check target agent exists: curl http://127.0.0.1:23000/api/agents | jq '.agents[].alias'
• For remote agents: curl http://<host-url>/api/agents | jq '.agents[].alias'
• Verify AI Maestro is running: curl http://127.0.0.1:23000/api/hosts/identity
• Check PATH: which send-aimaestro-message.sh

Agent not found:

• The script automatically searches all hosts and tries fuzzy matching
• If still not found, the error shows available hosts - check those for valid agent names
• Use list-agents.sh to see all agents on local host
• Use list-agents.sh <host-id> to see agents on a specific remote host
• Try partial names - fuzzy matching handles typos and abbreviations

APPENDIX: External Agents (ONLY if not in AI Maestro)

⚠️ SKIP THIS SECTION if you're running inside AI Maestro. This is ONLY for agents that:

• Are NOT managed by the AI Maestro dashboard
• Are NOT in a tmux session
• Are running from CI/CD, external scripts, or separate machines

External Agent Setup

# ONLY do this if you're external (not in AI Maestro)
export AI_MAESTRO_AGENT_ID="my-project"
export AI_MAESTRO_HOST_ID="my-hostname"  # Optional, defaults to current host

External Agent Example: Checking Messages

# Set identity (ONLY if external)
export AI_MAESTRO_AGENT_ID="my-project"

# Check inbox
check-aimaestro-messages.sh

# Read message
read-aimaestro-message.sh msg-123...

# Reply
reply-aimaestro-message.sh msg-123... "Thanks!"

External Agent Example: Sending Messages

# Set identity (ONLY if external)
export AI_MAESTRO_AGENT_ID="my-project"

# Send message to AI Maestro agent
send-aimaestro-message.sh lola@mini-lola \
  "Need help with schema" \
  "Can you review /docs/schema.md?" \
  normal request

References

• Quickstart
• Guidelines
• Architecture