AgentMail Skill

AgentMail enables communication between AI agents running in different tmux windows through a simple file-based mail system.

Overview

AgentMail is a CLI tool for inter-agent communication within tmux sessions. Messages are stored in .agentmail/mailboxes/ as JSONL files, providing persistent, file-locked message queues for each agent.

Prerequisites

• Must be running inside a tmux session
• AgentMail CLI must be installed and available in PATH
• Messages stored in .agentmail/ directory

Core Commands

Send a Message

agentmail send <recipient> "<message>"

Send a message to another agent. The recipient must be a valid tmux window name.

Examples:

agentmail send agent2 "Can you review the changes in src/api?"
agentmail send -r worker -m "Task completed"
echo "Build succeeded" | agentmail send agent2

Receive Messages

agentmail receive

Read the oldest unread message from your mailbox. Messages are delivered in FIFO order and marked as read after display.

List Recipients

agentmail recipients

List all tmux windows that can receive messages. Your current window is marked with [you].

Set Status

agentmail status <ready|work|offline>

Set your availability status:

• ready - Available to receive messages and notifications
• work - Busy working (suppresses notifications)
• offline - Not available (suppresses notifications)

Workflow

Checking for Messages

1. Run agentmail receive to check for new messages
2. If a message is available, read and process it
3. Optionally reply using agentmail send

Sending Messages

1. Run agentmail recipients to see available agents
2. Send your message: agentmail send <recipient> "<message>"
3. Confirm delivery via the returned message ID

Status Management

The plugin automatically manages your status:

• Session start: Status set to ready
• Session end: Status set to offline
• End of turn (Stop): Status set to ready, checks for new messages

Message Format

Messages include:

• ID: Unique 8-character base62 identifier (a-z, A-Z, 0-9)
• From: Sender's tmux window name
• To: Recipient's tmux window name
• Content: Message body

Best Practices

1. Check messages regularly - Use agentmail receive to stay informed
2. Keep messages concise - Focus on actionable information
3. Include context - Reference files, line numbers, or specific details
4. Respond promptly - Other agents may be waiting for your input
5. Use status appropriately - Set work when focusing on complex tasks

Integration with Claude Code

This plugin integrates with Claude Code hooks:

• SessionStart: Automatically sets status to ready and runs onboarding
• SessionEnd: Automatically sets status to offline
• Stop: Sets status to ready and checks for new messages

The hooks ensure agents are properly registered and can receive notifications from the mailman daemon.

Troubleshooting

"Not in a tmux session"

AgentMail requires tmux. Start a tmux session first.

"Recipient not found"

The recipient window doesn't exist. Check available windows with agentmail recipients.

"No unread messages"

Your mailbox is empty. Other agents haven't sent you messages yet.

Messages not being delivered

Ensure the mailman daemon is running: agentmail mailman --daemon