agent-mail
Multi-agent coordination via agent-mail CLI. Use when communicating with other agents, coordinating file access, sending/receiving messages, checking inbox, or reserving files. Triggers on "send message to agent", "check inbox", "reserve files", "coordinate with other agents", multi-agent workflows, file reservations, acknowledgements, "list agents", "delete agent", "clean up agents", "purge agents".
When & Why to Use This Skill
Agent-mail is a robust CLI-based coordination layer designed for multi-agent systems. It enables seamless asynchronous communication and resource management between AI agents via an MCP-compatible HTTP API. By providing structured messaging, file reservation systems, and task acknowledgments, it solves the critical challenges of concurrency and collaboration in complex agentic workflows, ensuring that multiple agents can work on the same project without resource conflicts or communication breakdowns.
Use Cases
- Multi-Agent Collaboration: Facilitating structured communication between specialized agents (e.g., a 'Researcher' agent sending findings to a 'Coder' agent) using an inbox and messaging system.
- Resource Locking and Concurrency: Preventing race conditions by allowing agents to 'reserve' specific files or paths, ensuring only one agent modifies a file at a time during parallel processing.
- Task Handoff and Tracking: Utilizing the acknowledgement (ack) system to verify that messages or tasks have been received and processed by the intended agent, reducing the risk of dropped tasks.
- Agent Lifecycle Management: Managing a fleet of agents within a project by registering identities, monitoring session heartbeats, and performing cleanups of inactive or completed agent sessions.
- Context Resumption: Allowing agents to retrieve their previous work context and profile information using 'whoami' and 'context' commands to maintain continuity across long-running or interrupted tasks.
| name | agent-mail |
|---|---|
| description | Multi-agent coordination via agent-mail CLI. Use when communicating with other agents, coordinating file access, sending/receiving messages, checking inbox, or reserving files. Triggers on "send message to agent", "check inbox", "reserve files", "coordinate with other agents", multi-agent workflows, file reservations, acknowledgements, "list agents", "delete agent", "clean up agents", "purge agents". |
Agent Mail CLI
Fast CLI for multi-agent coordination. Uses the server-backed MCP HTTP endpoints (no direct SQLite access).
Quick Reference
agent-mail --help # All commands
agent-mail <cmd> --help # Command details
agent-mail init # Create config directory and files
Core Commands
Messaging (HTTP API)
agent-mail send --to Agent --from Me --subject "..." --body "..."
agent-mail reply MESSAGE_ID --from Me --body "..."
agent-mail inbox AGENT [--limit N] [--urgent] [--bodies]
agent-mail ack MESSAGE_ID --agent AGENT
agent-mail search "query" [--limit N]
agent-mail thread THREAD_ID [--summarize]
File Reservations
# Server-backed (HTTP API via MCP server)
agent-mail reserve "path/*.js" --agent AGENT [--ttl 3600]
agent-mail renew --agent AGENT [--extend 1800]
agent-mail release --agent AGENT [paths...]
# Queries
agent-mail file_reservations active PROJECT
agent-mail file_reservations soon PROJECT [--minutes 30]
agent-mail file_reservations list PROJECT [--all]
Acknowledgements
agent-mail acks pending PROJECT AGENT
agent-mail acks overdue PROJECT AGENT [--hours 24]
agent-mail list-acks --project PROJECT --agent AGENT
Agent/Project Management
# Registration
agent-mail register --task "..." # First time (name auto-assigned)
agent-mail register --resume --task "..." # Resume most recent agent
agent-mail register --as AGENT --task "..." # Resume specific agent
# Quick orientation
agent-mail whoami # Auto-detects agent when possible
agent-mail context AGENT # Resume context summary
# Context & info
agent-mail context AGENT # Full context for resuming work
agent-mail whoami AGENT # Agent profile + recent commits
agent-mail list-agents # All agents in project
agent-mail contacts list AGENT
agent-mail list-projects
agent-mail health
# Cleanup (HTTP API)
agent-mail delete AGENT [--force] # Soft-delete (renames to Deleted-*)
agent-mail purge [--dry-run] # Hard-delete all soft-deleted agents
Session Management (Local)
# Sessions prevent two agents using the same identity concurrently
agent-mail session status [AGENT] # Check session status (all or specific)
agent-mail session heartbeat AGENT [--ttl N] # Extend session TTL (default 300s)
agent-mail session end AGENT # Release session lock
# Register with session control
agent-mail register --as AGENT --force # Override existing session
agent-mail register --as AGENT --ttl 600 # Set custom session TTL
Notes
- Project auto-detected from
$PWD; override with--project /path - Agent names are adjective+noun (BlueLake, GreenCastle, RedStone)
- Messages support Markdown
- All commands talk to the server over HTTP; this CLI does not read the server DB directly
- Sessions are stored locally in
~/.config/agent-mail-cli/sessions/ - Heartbeat runs automatically via PostToolUse hook (every 60s during active work)
- Initialize config with
agent-mail init --token ... --url ... - Optional (Claude Code): install hooks with
agent-mail hooks add(usesuv run python)