agent-mail
MCP Agent Mail for multi-agent coordination. Use when agents need file locks, messaging, inboxes, or conflict prevention. Handles macro_start_session, file_reservation_paths, send_message, threading, pre-commit guards.
How do I install this agent skill?
npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill agent-mailIs this agent skill safe to install?
- Gen Agent Trust Hubfail
The skill facilitates multi-agent coordination but includes setup and recovery scripts that perform high-risk operations. These include extracting authorization tokens from local configuration files, executing remote code via shell pipes and package managers, and installing persistent local utility scripts. It also creates a surface for indirect prompt injection by processing messages from multiple agents.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 2 issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
Using MCP Agent Mail
Core Insight: Without coordination, multiple agents overwrite each other's work. Agent Mail provides identities, messaging, and file reservations to prevent conflicts.
When to Use What
| Situation | Action |
|---|---|
| Starting any agent session | macro_start_session |
| About to edit files | file_reservation_paths → edit → release_file_reservations |
| Need to tell another agent something | send_message with thread_id |
| Picking up someone else's work | macro_prepare_thread |
| Can't message an agent | request_contact → wait for approval |
| Server seems broken | Use health_check() first; CLI-only: doctor check --verbose → doctor repair --yes |
THE EXACT PROMPT — Session Bootstrap
Call this at the start of every agent session:
macro_start_session(
human_key="/abs/path/to/project",
program="claude-code",
model="YOUR_MODEL",
task_description="Working on auth module"
)
Returns: {project, agent, file_reservations, inbox}
This single call: ensures project exists → registers your identity → fetches inbox.
Core Operations
| Task | Tool |
|---|---|
| Bootstrap session | macro_start_session(human_key, program, model, task_description) |
| Send message | send_message(project_key, sender_name, to, subject, body_md) |
| Reply in thread | reply_message(project_key, message_id, sender_name, body_md) |
| Check inbox | fetch_inbox(project_key, agent_name, limit=20) |
| Reserve files | file_reservation_paths(project_key, agent_name, paths, ttl_seconds) |
| Release files | release_file_reservations(project_key, agent_name) |
| Search messages | search_messages(project_key, "query") |
The Four Macros
| Macro | When to Use |
|---|---|
macro_start_session | Bootstrap: project → agent → inbox |
macro_prepare_thread | Join existing thread with summary |
macro_file_reservation_cycle | Reserve → work → auto-release |
macro_contact_handshake | Cross-agent contact setup |
Fast Resource Reads (No Tool Call Required)
| Need | Resource |
|---|---|
| List agents | resource://agents/{project_key} |
| Inbox | resource://inbox/{agent}?project=/abs/path&limit=20 |
| Thread | resource://thread/{thread_id}?project=/abs/path&include_bodies=true |
| Ack-required | resource://views/ack-required/{agent}?project=/abs/path |
File Reservations
Reserve Before Editing
file_reservation_paths(
project_key="/abs/path/project",
agent_name="GreenCastle",
paths=["src/auth/**/*.ts"],
ttl_seconds=3600,
exclusive=true,
reason="bd-123"
)
Returns: {granted: [...], conflicts: [...]}
Conflict Resolution
If conflicts exist:
- Wait — TTL will expire
- Coordinate — Message the holder
- Share — Use
exclusive=false
Release When Done
release_file_reservations(project_key="/abs/path/project", agent_name="GreenCastle")
Beads Integration
Use bead IDs as your threading anchor:
1. Pick work: br ready --json → choose bd-123
2. Reserve files: file_reservation_paths(..., reason="bd-123")
3. Announce: send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
4. Work: Reply in thread with progress
5. Complete: br close bd-123, release_file_reservations(...), final message
Bead ID (often bd-###) goes in: thread_id, subject prefix, reservation reason, commit message
Quick Troubleshooting
| Error | Fix |
|---|---|
| "sender_name not registered" | Call macro_start_session first |
| "FILE_RESERVATION_CONFLICT" | Wait, coordinate, or use exclusive=false |
| "CONTACT_BLOCKED" | Use request_contact, wait for approval |
| Empty inbox | Check since_ts, urgent_only, agent name spelling |
| Server unreachable | Use health_check() or resource://config/environment to confirm MCP server is up; if CLI-only, check curl http://127.0.0.1:8765/health |
| Guard blocks commit | Set AGENT_NAME env var; bypass: AGENT_MAIL_BYPASS=1 git commit |
Doctor Diagnostics (CLI-only, optional)
# Quick health check (CLI daemon)
curl http://127.0.0.1:8765/health
# Full diagnostics (CLI)
uv run python -m mcp_agent_mail.cli doctor check --verbose
# Preview repairs (dry run, CLI)
uv run python -m mcp_agent_mail.cli doctor repair --dry-run
# Apply repairs (CLI)
uv run python -m mcp_agent_mail.cli doctor repair --yes
Agent Identity
Agents get adjective+noun names: GreenCastle, BlueLake, RedBear.
Best practice: Omit name parameter to auto-generate valid names.
register_agent(
project_key="/abs/path/project",
program="claude-code",
model="YOUR_MODEL",
task_description="Auth refactor"
) # name auto-generated
Human Overseer
Send urgent messages to agents from the web UI at http://127.0.0.1:8765/mail:
- Click "Human Overseer" mode
- Compose with
importance: urgent - Select target agents
Agents see urgent messages via fetch_inbox(..., urgent_only=true).
Pre-Commit Guard
install_precommit_guard(project_key="/abs/path", code_repo_path="/abs/path")
- Set
AGENT_NAMEenv var so guard knows who you are - Bypass emergency:
AGENT_MAIL_BYPASS=1 git commit -m "fix" - Warning mode:
AGENT_MAIL_GUARD_MODE=warn
Search Syntax (FTS5)
"exact phrase"
prefix*
term1 AND term2
term1 OR term2
(auth OR login) AND NOT admin
References
| Topic | Reference |
|---|---|
| All MCP tools | TOOLS.md |
| Workflow patterns | WORKFLOWS.md |
| MCP resources | RESOURCES.md |
| Cross-project setup | CROSS-PROJECT.md |
| Doctor & recovery | RECOVERY.md |
| Installation | INSTALL.md |
| Fix MCP config | FIX-MCP-CONFIG.md |
| Product bus, build slots, internals | ADVANCED.md |
Validation
# Server health
curl http://127.0.0.1:8765/health
# → {"status": "healthy"}
# Start server if needed
am
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations/agent-mail">View agent-mail on skillZs</a>