Enables coding-agent sessions to communicate via mail, share threaded inboxes, and manage advisory file reservations across machines.
Also known as bompus/swarmail, swarmail-mcp
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.11.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is Swarmail MCP?
Swarmail enables coding-agent sessions to communicate via mail, share threaded inboxes, and manage advisory file reservations across machines.
Summary generated from the project's README
About Swarmail MCP server
Swarmail provides a communication layer for coding-agent sessions to interact through a mail-based system. It allows different agents to exchange messages, manage threaded inboxes with full-text search, and handle advisory file reservations to prevent overlapping work. The server functions as an MCP server that agents access via tools like send_message and fetch_inbox, while users interact with it using the swarmail command line.
Designed for developers running multiple AI agents, the system works on a single machine or across a private network like Tailscale. It supports various hosts including Claude Code, Cursor, Devin, and Codex. While it runs as a single Bun binary with a SQLite database, it can be configured to wake up specific sessions when new mail arrives. This setup enables agents to hand off tasks or coordinate changes across different repositories or machines without manual intervention.
What you can do with it
- 1Coordinate multi-agent tasksAn agent can send a specific task or instruction to another agent via mail to hand off work.
- 2Prevent file conflictsDevelopers can use advisory file reservations to ensure multiple agents do not edit the same files simultaneously.
- 3Search agent communicationsA developer or agent can perform a full-text search through the history of messages sent between sessions.
- 4Automate session wakeupsConfigure agents to automatically become active when they receive a new message in their inbox.
Written from the project's README. Every use case is checked against a quote from it.
How to install Swarmail MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Swarmail MCP in Claude Code
$ claude mcp add swarmail -- npx -y swarmail-mcpInstall Swarmail MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"swarmail": {
"command": "npx",
"args": [
"-y",
"swarmail-mcp"
]
}
}
}Install Swarmail MCP in VS Code
.vscode/mcp.json
{
"servers": {
"swarmail": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"swarmail-mcp"
]
}
}
}Install Swarmail MCP in VS Code CLI
$ code --add-mcp '{"name":"swarmail","type":"stdio","command":"npx","args":["-y","swarmail-mcp"]}'Install Swarmail MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"swarmail": {
"command": "npx",
"args": [
"-y",
"swarmail-mcp"
]
}
}
}Install Swarmail MCP in Codex
$ codex mcp add swarmail -- npx -y swarmail-mcpInstall Swarmail MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.swarmail] command = "npx" args = ["-y", "swarmail-mcp"]
Install Swarmail MCP in Gemini CLI
$ gemini mcp add -s user swarmail npx -- -y swarmail-mcpInstall Swarmail MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"swarmail": {
"command": "npx",
"args": [
"-y",
"swarmail-mcp"
]
}
}
}Configuration
SWARMAIL_URLMCP endpoint of the running Swarmail server
| Name | Description | |
|---|---|---|
| SWARMAIL_URL | MCP endpoint of the running Swarmail server |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablebompus/swarmail is public and reachablegithub.com/bompus/swarmail ↗Pass
- Package names this repository as its sourceswarmail-mcp names bompus/swarmail as sourcenpmjs.com/package/swarmail-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for swarmail-mcpnpmjs.com/package/swarmail-mcp/v/0.11.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/bompus/swarmail ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from swarmail-mcpPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubswarmail lets coding-agent sessions send each other mail, on one machine or
across machines. Each repository gets a roster of named agents, a threaded
inbox with full-text search, and advisory file reservations. Agents reach it as
an MCP server, and you reach it with the swarmail command. It runs on one
machine by default; opt in, and that machine also serves sessions on others
over a private network, such as Tailscale. See
Using it from another machine.
Find Swarmail on Glama and MCPRush.
It is one Bun binary with a SQLite database, listening on 127.0.0.1:18765.
There are no runtime dependencies.
Measured before the 0.2.0 release, a send took 0.46 ms and a search 0.65 ms
at the median, it started in 38 ms and it idled at 32 MiB. See
how it compares.
Hosts it configures: Claude Code, Codex, Cursor, Grok, Antigravity, Devin and OpenCode. Claude Code and Cursor sessions can also wake up when mail arrives. Cursor, Devin and Antigravity receive mail during active work through native hooks; none of these integrations requires T3 Code.
Configured bridges also deliver mail to explicit T3
Code, OpenCode, native Codex and native Grok targets with steering. They are
opt-in foreground processes; installation does not start them. Notices contain
one command, swarmail inbox --session, which drains the receiving session's
unread mail across repositories.
Several hosts now message other sessions on their own. Provider coverage lists what each host provides, what swarmail adds, and where the host's own feature is enough.
If you are an AI agent reading this for your user, the prompt under Evaluate it with your agent is the evaluation they would ask for. Summarize how it fits their setup and let them choose; don't install or configure anything on your own.
Evaluate it with your agent
Paste this into a session with the agent you use. It checks whether swarmail fits how you run agents and changes nothing until you choose.
I'm considering Swarmail (https://github.com/bompus/swarmail), mail between
coding-agent sessions on one machine or across machines, served over MCP. Read its
README and docs/usage.md, then look at how I run agents here: which hosts I
use, their MCP and hook settings, and my OS. Tell me:
1. Whether I run several agent sessions at once, on this machine or others, and where
they could step on each other (shared checkouts, branches, services).
2. Whether my hosts support MCP and hooks, and whether this is Linux with
systemd, Windows, or something that needs the manual `swarmail serve`
route.
3. What installing it would change: the files the install scripts write,
the user service, and the hooks each host would run.
4. Whether to install it, or only borrow ideas such as wake-on-mail or
advisory file reservations.
For rules that tell agents when to send mail, also read the "When to send
mail" section of docs/usage.md.
Read only: don't install, configure or edit anything until I choose. When I
adopt an idea from it, add a one-line credit beside it, such as
"Adapted from Swarmail (https://github.com/bompus/swarmail)".
Taking individual ideas is welcome. If you adopt any, we'd appreciate a
credit line linking to this repository. Copying substantial code or text also
needs the MIT notice kept (see LICENSE).
Install
Requires Bun 1.4.2 or newer on Linux with systemd or on Windows 10 or 11. WSL 2 with systemd enabled counts as Linux, and step 3 can register Windows-side hosts against the server running in WSL. Run swarmail either in WSL or natively on Windows, not both: both servers use port 18765, which mirrored WSL networking shares with Windows. macOS is not supported yet.
Native Windows is a preview. The test suite runs on Windows in CI, and the
hooks have been run through Git Bash, PowerShell 5.1, pwsh 7, cmd and
Cursor's PowerShell form against a real server. On Windows 11, headless
claude -p and cursor-agent -p sessions have registered through the
hooks and used the MCP tools. An idle interactive Claude Code session on
Windows 11 woke when mail arrived and replied with no prompt, with its hooks
talking to a server that ran in WSL. Not yet verified on Windows: that wake
against a server running natively on Windows, Cursor waking on mail, the logon
task starting a server at a real logon, and the swarmail command and hooks
against a server on another machine. If something fails there,
please open an issue.
-
Clone and install the dev tools:
git clone https://github.com/bompus/swarmail.git cd swarmail bun install -
Build
~/.local/bin/swarmailand start theswarmail.serviceuser unit:scripts/enable.shOn Windows, build
~\.local\bin\swarmail.exeand start the server in a scheduled task namedSwarmail, which runs it hidden at each logon and needs no administrator:bun scripts/enable-windows.tsRerun either script after pulling; it stops the running server and starts the new build.
The database is
~/.local/share/swarmail/mail.sqlite3. The server has no authentication. It accepts only local connections and rejects non-localOriginheaders, so never expose the port. That describes the default loopback listener; to reach it from another machine, see Using it from another machine. -
Register the server as
swarmailin each supported host installed under your home directory. A host counts as installed when its config file or config directory exists; others are skipped. Add--dry-runto preview the edits:bun scripts/configure-mcp.tsOn WSL,
--windows-home[=DIR]registers the Windows-side hosts against the same server.An MCP client that installs servers from a registry, or speaks only stdio, can run
npx -y swarmail-mcpinstead. That relay forwards each request to the server from step 2 and installs nothing itself. Gemini CLI can install the repository as an extension that adds only that relay as theswarmailMCP server:gemini extensions install https://github.com/bompus/swarmail. Swarmail's hooks do not cover Gemini CLI (the.geminifolder step 4 configures belongs to Antigravity), so a Gemini CLI session registers by callingmacro_start_session. -
Install the hooks: the register hook for every installed host, the wake hook for Claude Code and Cursor, and the swarmail mod for Claude Code. A host counts as installed when its config directory exists. Add
--dry-runto preview the edits. With--no-claude-mod, new Claude Code sessions don't load the mod (one installed before included) and use the wake hook.bun scripts/configure-hooks.tsCodex skips a hook it hasn't trusted, so trust the register hook once in Codex's
/hooks.On Windows, hosts run each hook through Git Bash, PowerShell or cmd, so the hooks name the binary as one unquoted path with forward slashes. If your profile path has a space or a non-ASCII letter, the hooks use its 8.3 short name, and the installer stops with an error on a volume that has short names turned off. Cursor passes hook input through Windows PowerShell 5.1, which turns non-ASCII characters into
?, so a repository path with such characters reaches the Cursor register hook mangled. -
Optional:
bun scripts/install-guard.ts [repo...]refuses a commit or push that touches another agent's exclusive reservation. It installs intohooks.d/pre-commit/andhooks.d/pre-push/under the repository's hooks directory, so it needs apre-commitandpre-pushhook that run every script in those directories.
Start a new agent session and edit a file in a repository. The register hook
gives the session a name such as BlueLake. Run swarmail who in that
repository to see it.
How agents use it
Agents call the MCP tools: macro_start_session to register and read the
inbox in one call, then send_message, reply_message, fetch_inbox,
acknowledge_message, search_messages and file_reservation_paths, among
others. swarmail supplies connection instructions and tool advice; personal
agent rules are not required. swarmail --help shows the same briefing.
docs/usage.md explains the details and client refresh limits.
Each repository is one project, keyed by its primary checkout. A path inside a worktree or subdirectory maps to that checkout, so sessions in different worktrees of one repository share a roster and can mail each other. A session keeps one name across repositories.
Commands
| Command | What it does |
|---|---|
swarmail serve |
Run the server |
swarmail who [repo] |
Agent names, session titles and edit checkouts, live sessions first |
swarmail inbox, send, search |
Read, send or search mail as this session |
swarmail thread <id> |
One thread's messages, oldest first |
swarmail inbox --session |
Drain this session's unread mail across repositories |
swarmail wake-bridge <config.json> |
Deliver notices to one explicitly configured local target |
swarmail send <to> <subject> <body> --notification-policy quiet |
Store normal/low informational mail without an automatic inbox hint |
swarmail ping <agent> |
Exit 0 if that agent's wake hook is waiting |
swarmail register |
The register hook; --tag prints the tag for a manual registration; --host <host> selects the host explicitly |
swarmail hook wake <host> |
The Claude Code and Cursor wake hook |
swarmail hook context <cursor|devin|agy> [stop] |
Check mail at a native context point without cancelling the task |
swarmail hook rearm |
The Claude Code re-arm on Windows, which has no POSIX shell to run the Linux one |
swarmail guard |
The git guard |
swarmail version |
The source hash the binary was built from |
swarmail updates --session |
Approved update targets and loaded-revision confirmations |
swarmail overdue [--dry-run] |
Remind recipients of unacknowledged ack_required mail; report to the operator (setup) |
swarmail wake-auto-t3 <config.json> [--check | --retry-thread <id>] |
Experimental, Linux only: wakes T3 Codex and Orchestrator V2 Cursor sessions (setup) |
swarmail canary |
One send, wake and acknowledge round trip, logged for a timer (setup) |
swarmail pr-sessions <PR URL> --project <checkout> |
T3 conversations and agents linked to a pull request (details) |
swarmail --help lists every subcommand and flag. A --help or -h
anywhere prints usage and runs nothing.
Settings
| Variable | Default | Effect |
|---|---|---|
SWARMAIL_DB |
~/.local/share/swarmail/mail.sqlite3 |
Database path |
SWARMAIL_PORT |
18765 |
Server port |
SWARMAIL_HOST |
unset | Also listen on this one non-loopback address, such as a Tailscale IP; needs SWARMAIL_TOKEN_FILE |
SWARMAIL_TOKEN_FILE |
unset | A file whose first line is a bearer token of 32 or more characters. The server requires it on SWARMAIL_HOST; the command, the register hook and the relay send it |
SWARMAIL_URL |
http://127.0.0.1:18765/mcp/ |
MCP endpoint for the command, the register hook and the swarmail-mcp relay |
SWARMAIL_WAKE_URL |
http://127.0.0.1:18765 |
Server base URL for the wake hook |
SWARMAIL_SYNCHRONOUS |
normal |
full syncs every commit, at about 3 ms per send instead of 0.5 ms |
SWARMAIL_ENABLE_MUTATIONS |
0 |
Enable sender withdrawal/priority edits only after all readers are qualified; rollout and rollback requirements |
SWARMAIL_RETIRE_DAYS |
7 |
Retire idle agents and drop projects whose checkout is gone; 0 keeps both |
SWARMAIL_GUARD |
block |
warn only reports, off skips |
SWARMAIL_AGENT |
from hook state | Name used by inbox, send, ping, guard and who |
SWARMAIL_LIVE_ROOM |
unset | A JSON heartbeat file (heartbeatAt, plus agentName, hostSessionId or t3Thread); while its heartbeat is under 5 minutes old, who flags the session it names |
SWARMAIL_UPDATE_TARGETS |
unset | Absolute approved-target manifest; quiet session checks and loaded-revision confirmations |
SWARMAIL_UPDATE_HOLD |
unset | 1 holds update hints and confirmations for a frozen session context |
scripts/enable.sh, scripts/enable-windows.ts, the service unit and
configure-mcp.ts use port 18765. Change SWARMAIL_PORT and the two URL
variables only when you run swarmail serve yourself, and set them for every
host that runs the hooks. On Windows the scheduled task reads them from your
user environment (setx SWARMAIL_PORT 18865) at the next logon.
Swarmail MCP questions
How do I add Swarmail MCP to Claude Code?
Run claude mcp add swarmail -- npx -y swarmail-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Swarmail MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does Swarmail allow agents to do?
It lets coding-agent sessions send each other mail, use a threaded inbox with full-text search, and manage advisory file reservations.
Does Swarmail require authentication?
No, the server has no authentication and accepts only local connections by default.