agentmail

AgentMail

A Go CLI tool for inter-agent communication within tmux sessions. Agents running in different tmux windows can send and receive messages through a simple file-based mail system.

Features

• Asynchronous messaging - Send messages to agents in other tmux windows without blocking
• FIFO message queue - Messages delivered in order, oldest first
• Simple file-based storage - Messages stored in .agentmail/ as JSONL files
• Concurrent-safe - File locking ensures atomic operations between agents
• Minimal dependencies - Built with Go standard library + lightweight CLI framework
• Ignore lists - Filter out windows you don't want to communicate with
• Stdin support - Pipe messages from other commands
• Daemon notifications - Background mailman daemon monitors mailboxes and notifies agents
• Agent status tracking - Agents can set status (ready/work/offline) for smart notifications
• MCP server - Model Context Protocol server for Claude Code, Codex CLI, and Gemini CLI
• Claude Code integration - Plugin and hooks for AI agent orchestration
• Cleanup utility - Remove stale recipients, old messages, and empty mailboxes

Requirements

• Go 1.25.7 or later
• tmux (must be running inside a tmux session)
• Linux or macOS

Installation

Homebrew (macOS/Linux)

The easiest way to install AgentMail is via Homebrew:

brew install UserAd/agentmail/agentmail

Or add the tap first, then install:

brew tap UserAd/agentmail
brew install agentmail

Note: If you have another package named agentmail installed, use the full tap path: brew install UserAd/agentmail/agentmail

From Releases

Download the latest binary for your platform from the Releases page.

Available platforms:

• Linux (amd64, arm64)
• macOS (amd64, arm64)

From Source

# Clone the repository
git clone https://github.com/UserAd/AgentMail.git
cd AgentMail

# Build
go build -o agentmail ./cmd/agentmail

# Or install to $GOPATH/bin
go install ./cmd/agentmail

Quick Start

# Start a tmux session with multiple windows
tmux new-session -s agents -n agent-1
tmux new-window -t agents -n agent-2

# In agent-1 window: send a message
agentmail send agent-2 "Hello from agent-1!"
# Output: Message #xK7mN2pQ sent

# In agent-2 window: receive the message
agentmail receive
# Output:
# From: agent-1
# ID: xK7mN2pQ
#
# Hello from agent-1!

Commands

send

Send a message to another agent (tmux pane).

agentmail send [flags] [<recipient>] [<message>]

Arguments (positional or flags):

• <recipient> - Target pane address (required). Accepts three forms:
  • Full: session:window.pane (e.g., AgentMail:editor.1)
  • Medium: :window.pane (e.g., :editor.1) — session inferred from current
  • Short: window (e.g., editor) — backward compatible, resolves if single pane
• <message> - Message content (optional if using stdin)

Flags:

• -r, --recipient <address> - Recipient pane address
• -m, --message <text> - Message content

Flags take precedence over positional arguments.

Pane Addressing:

When using the short form (window name only), AgentMail resolves it to a specific pane:

• If the window has one pane: message is sent to that pane
• If the window has multiple panes: returns an ambiguity error listing all pane addresses

Example ambiguity error:

Ambiguous recipient: window 'editor' has 3 panes. Use AgentMail:editor.0, AgentMail:editor.1 or AgentMail:editor.2

Examples:

# Send with positional arguments
agentmail send agent-2 "Task completed successfully"

# Send to specific pane (full address)
agentmail send AgentMail:editor.1 "Review this code"

# Send to specific pane (medium address)
agentmail send :editor.1 "Update from pane 0"

# Send with flags (equivalent)
agentmail send -r agent-2 -m "Task completed successfully"
agentmail send --recipient AgentMail:editor.0 --message "Task completed"

# Send via stdin
echo "Results from analysis" | agentmail send agent-2
echo "Results" | agentmail send -r :editor.1

# Send multi-line content
cat report.txt | agentmail send agent-2

Exit codes:

• 0 - Message sent successfully
• 1 - Error (invalid recipient, missing message, etc.)
• 2 - Not running inside tmux

receive