agent-mail
Made by JeffMCP 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.
Works With
Quality and Utility come from canonical skill metadata. Community ratings appear separately as stars when subscriber reviews exist.
Subscribe to download
Public previews are available, but downloads, CLI sync, and premium content require an active subscription.
Sign In to Subscribe- Full skill content with deterministic versioning
- CLI sync + local search index
- Access to Jeffrey’s premium library
Save to your account
Saved skills live in your cloud list. Run jsm sync on each machine to pull them locally.
What's New with this Skill
2Updates, enhancements, and release notes for this skill.
Updated: agent-mail, matched to the Rust server's actual behavior
Much of the skill described the legacy Python server. On the current Rust server (am 0.3.36), cross-project sends are refused, conflicting file reservations are not granted, and the CLI is am rather than the old Python module. The skill now documents what the server really does.
- Cross-project sends are refused with CROSS_PROJECT_RECIPIENT, even between linked projects
- Conflicting file reservations are not granted; the auto-release reservation cycle releases before it returns
- Commands use the am CLI; start the server with am serve-http
- /health returns ready and health_check returns ok; search uses Tantivy
- Features the Rust server does not have were removed from the skill
Checked against am 0.3.36 and the mcp_agent_mail_rust source.
- Cross-project mail. Linking projects does not allow sending across them: the server refuses with
CROSS_PROJECT_RECIPIENT. The cross-project workflow is rewritten around what the server permits. - Reservations. A conflicting reservation is not granted.
macro_file_reservation_cyclewithauto_releasereleases before it returns, so it gives no window to do work in between.
New: Agent Mail brings file locks, identity, and inboxes to swarms that would otherwise overwrite each other
Multi-agent coding stacks need three things to coexist in the same repo: stable identities, message threads, and atomic file reservations. MCP Agent Mail provides all three through a small set of tools plus four macros. The bead ID is the natural thread ID, FTS5 search lets one agent find another's prior work, and a pre-commit guard refuses commits that touch files reserved by someone else.
- One-call bootstrap: macro_start_session ensures the project exists, registers an identity (auto-generated adjective+noun), and fetches the inbox in a single MCP request
- File reservations have TTLs, an exclusive flag, and a reason string. The response is {granted: [...], conflicts: [...]}; on a conflict the agent waits for the TTL, messages the holder, or sets exclusive=false to share
- Bead ID is the coordination thread ID: reason="bd-123", thread_id="bd-123", subject "[bd-123] Starting...", and the commit message tag. One ID across reservation, message, bead, and commit
- Four macros (start_session, prepare_thread, file_reservation_cycle, contact_handshake) collapse the common multi-call patterns into one round trip
- Resource reads (resource://inbox/{agent}, resource://thread/{id}, resource://views/ack-required/{agent}) skip the tool round-trip when the agent only needs to read state
- FTS5 message search: "exact phrase", prefix*, term1 AND term2, (auth OR login) AND NOT admin. Useful when a fresh agent needs to find what the previous agent learned
- Pre-commit guard refuses a commit that touches files reserved by another agent. Set AGENT_NAME so the guard knows who you are; bypass with AGENT_MAIL_BYPASS=1 git commit, or run it in warn mode
- Human Overseer web UI at http://127.0.0.1:8765/mail lets a person send importance: urgent messages; agents read them via fetch_inbox(..., urgent_only=true)
- request_contact (then wait for approval) when you can't message an agent yet; when the server seems broken, check health first, then doctor check --verbose and doctor repair --yes
Without coordination, two agents working in the same repo will overwrite each other's edits the moment their reads-then-writes interleave. Agent Mail solves the lock half by handing out file reservations with TTLs, the identity half by registering each agent under an adjective+noun name like GreenCastle or BlueLake (auto-generated when the name parameter is omitted), and the messaging half by keeping inboxes and threads addressable by agent name.