agent-mail
Coordinate with other AI agents via project-local Maildir messaging. Use when operating in tandem mode with Claude, Gemini, or other agents. Enables claiming tasks, reporting completion, handling blocks, and synchronizing work across terminals.
When & Why to Use This Skill
Agent-mail is a specialized project-local messaging system designed to facilitate seamless coordination between multiple AI agents. By utilizing Maildir semantics, it allows agents like Claude and Gemini to operate in tandem, enabling them to claim tasks, synchronize work across different terminals, and provide real-time status updates. This skill is essential for complex, multi-agent workflows where clear communication and task handoffs are critical for project success.
Use Cases
- Multi-Agent Tandem Operations: Coordinate complex tasks between different LLMs (e.g., Claude for development and Gemini for documentation) within the same project directory.
- Task Claiming and Conflict Resolution: Prevent redundant work by allowing agents to 'broadcast' which task they are currently claiming and their progress status.
- Automated Handoffs and Completion Reporting: Streamline the workflow by having agents automatically notify their partners when a task is finished, including the location of the output files.
- High-Priority Blocker Notifications: Enable agents to send urgent alerts when they are stuck or require human intervention, ensuring project bottlenecks are identified immediately.
- Cross-Terminal Work Synchronization: Maintain a unified communication log and state when running multiple agent sessions in separate terminal environments.
| name | agent-mail |
|---|---|
| description | Coordinate with other AI agents via project-local Maildir messaging. Use when operating in tandem mode with Claude, Gemini, or other agents. Enables claiming tasks, reporting completion, handling blocks, and synchronizing work across terminals. |
Agent Mail
Project-local messaging system for multi-agent coordination. Email semantics for AI agents working together.
When to Use
Invoke when:
- Operating in tandem mode with other AI agents (Claude + Gemini, multiple Claudes)
- Starting a session and need to check for messages from partners
- Claiming a task and need to notify other agents
- Completing work and need to report handoff
- Blocked and need to notify partners urgently
- Need to coordinate or synchronize work across terminals
Pre-requisites
Check if agent-mail is initialized:
ls .agent-mail/ # Should exist in project root
If not initialized:
npx tsx ~/Projects/leegonzales/agent-mail/src/mail.ts init
Core Rituals (MANDATORY)
1. Session Start
Before ANY work, join and check inbox:
agent-mail join claude
agent-mail check claude
If unread messages exist:
agent-mail read claude
Process all messages before proceeding.
2. Before Claiming Work
Notify partners before starting any task:
agent-mail broadcast claude "Claiming Task" "Claiming IE-XX. Starting now."
3. After Completing Work
Report completion immediately:
agent-mail broadcast claude "Task Complete" "IE-XX complete. Output at: path/to/result"
4. When Blocked
Notify with HIGH priority:
agent-mail send claude gemini "BLOCKED" "IE-XX blocked: reason" --priority high
5. Periodic Check-in
For long tasks (>5 minutes):
agent-mail broadcast claude "Status Update" "Still on IE-XX. 60% complete."
Message Types
| Subject | Purpose |
|---|---|
Claiming Task |
Announcing you're taking a task |
Task Complete |
Work finished, ready for handoff |
BLOCKED |
Cannot proceed, need help |
Status Update |
Progress on long task |
Question |
Need clarification |
Answer |
Responding to question |
Handoff |
Explicitly passing work |
Sync Request |
Asking for partner status |
Quick Reference
# Project
agent-mail init # Initialize in current project
agent-mail join claude # Register as agent
agent-mail who # See active agents
agent-mail info # Project info
# Messaging
agent-mail check claude # Peek inbox (no mark)
agent-mail read claude # Read + mark as read
agent-mail send claude gemini "Subject" "Body"
agent-mail broadcast claude "Subject" "Body"
agent-mail reply claude <id> "Body"
agent-mail status # All inboxes
agent-mail history claude 10 # Message history
Integration with Beads
When using beads task tracking:
Claim in beads first, then notify:
bd update IE-XX --status in_progress --assignee Claude agent-mail broadcast claude "Claiming Task" "Claimed IE-XX in beads"Close in beads, then notify:
bd close IE-XX "Completed" agent-mail broadcast claude "Task Complete" "IE-XX closed"
Examples
See references/examples.md for full conversation examples.