Before: You're the Middleman

Your frontend agent needs an API endpoint. Your backend agent can build it. But they can't talk directly.

❌ You copy-paste requests between agents
❌ You relay responses manually
❌ You're the bottleneck in agent coordination
❌ Context gets lost in translation

After: Direct Agent Communication

Agents send messages directly to each other. You orchestrate from above, not relay from between.

✅ Agents request work from each other
✅ Structured messages with priorities
✅ Persistent inboxes for each agent
✅ Natural language or command-line

How It Works

Watch agents communicate without human intervention

Step 1: Agent Receives Message

Agent gets notified immediately when another agent sends a message.

Step 2: Agent Reviews Inbox

Opens inbox to see full message details, context, and priority.

Step 3: Agent Sends Reply

Composes and sends structured response with results.

Complete Exchange

Full agent-to-agent conversation without human relay.

🎯 Key Insight

Whether using natural language (Claude Code skills) or command-line tools, the underlying system is identical. Messages are persistent, searchable, and structured.

Two Ways to Use It

Choose the mode that fits your AI agent

✨

Skills Mode

Natural Language (Claude Code Only)

You say:

"Send a message to backend-architect asking about the API endpoint status"

Claude automatically:

✅ Formats the message
✅ Sends it to the right agent
✅ Confirms delivery

Claude loads the messaging skill automatically

No commands needed - just describe what you want

Advantages:

✅ Zero command memorization
✅ Context-aware
✅ Natural conversation flow
✅ Progressive disclosure

🔧

Manual Mode

Command-Line (Universal)

Direct command:

send-aimaestro-message.sh backend-architect \
  "API endpoint status" \
  "What's the status?" \
  normal \
  request

Direct command-line - works with any agent

Check inbox with command-line tools

Advantages:

✅ Works with ANY AI agent
✅ Shell scripts & automation
✅ Full parameter control
✅ No Claude Code needed

💡 Which Mode Should You Use?

Using Claude Code with skills installed? → Use Skills Mode (natural language, zero commands)

Using Aider, Cursor, or other agents? → Use Manual Mode (universal command-line tools)

Real-World Example

Frontend agent needs an API from backend agent

📤

Frontend Requests

"Send a request to backend-architect: Need POST /api/users endpoint with email and password"

🔨

Backend Builds

Checks inbox, sees request, implements the endpoint, tests it

✅

Backend Replies

"Endpoint ready at routes/users.ts:45"

⏱️ Time saved: 5-10 minutes per request

No context switching. No copy-pasting. No relay work.

Messaging Features

📨 Dual-Channel System

File-based persistent messages + instant tmux notifications

✅ Persistent inbox for each agent
✅ Instant popup alerts for urgent messages
✅ Searchable message history

🎯 Priority Levels

Four priority levels for proper urgency management

🚨 Urgent - Production issues
⚠️ High - Blocking work
📋 Normal - Regular requests
💡 Low - Nice-to-have

📝 Message Types

Structured message types for clear communication

📤 Request - Need work from another agent
💬 Response - Answering a request
📢 Notification - FYI updates
📊 Update - Progress reports

🔧 Claude Code Skills

Natural language integration for Claude Code agents

✅ Progressive disclosure (loads when needed)
✅ Automatic session detection
✅ Structured message formatting

Quick Start

🎯 Easy Install (Recommended)

Run the automated installer - installs both scripts and skill with one command:

cd /path/to/ai-maestro
./install-messaging.sh

The installer checks prerequisites, installs everything, and verifies it works. Takes < 1 minute.

Or install manually:

Skills Mode (Claude Code)

Install the skill: Copy skills/agent-messaging/ to ~/.claude/skills/ (install guide)
Ask Claude naturally: "Send a message to backend-architect asking about the API"
Claude handles everything: Formats, sends, and confirms delivery
Check inbox: "Do I have any messages?" or "Check my inbox"

💡 Time to first message: < 1 minute

Just ask Claude - no commands to remember!

Manual Mode (Universal)

Install scripts: Copy messaging_scripts/ to ~/.local/bin/ (install guide)

Send a message:

send-aimaestro-message.sh backend-architect \
  "Need API endpoint" \
  "Please implement POST /api/users" \
  high \
  request

Check inbox:
```
check-and-show-messages.sh
```

💡 Time to first message: < 2 minutes

One command - works with any AI agent!

Read Full Documentation

Documentation

🚀

Quickstart Guide

Get started in under 5 minutes

📚

Messaging Guide

Comprehensive reference

📋

Best Practices

Communication guidelines

🏗️

Architecture

Technical deep-dive

Ready to let your agents collaborate?

Free, open source, and works with any AI agent.

Get Started on GitHub Back to AI Maestro