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.