Swarmail

What the Swarmail MCP server does

The Swarmail MCP server provides local communication between coding-agent sessions running on the same machine. It organizes agents into repository-specific rosters and stores messages in threaded inboxes. Full-text message search and advisory file reservations help agents find prior discussion and signal which paths they are using.

The service runs as one Bun binary with a SQLite database. Its default listener is 127.0.0.1:18765, and the server accepts local connections only. It has no authentication and rejects non-local Origin headers, so the port should not be exposed outside the machine.

How it works

Agents connect through MCP and can call macro_start_session to register and read an inbox in one operation. Other documented tools include send_message, reply_message, fetch_inbox, acknowledge_message, search_messages, and file_reservation_paths. The command-line client provides operational commands such as swarmail who and swarmail inbox --session.

Repository identity is based on the primary checkout, so paths in a worktree or subdirectory map back to that checkout. Registration hooks assign sessions names such as BlueLake. Optional guard installation adds pre-commit and pre-push checks that refuse changes involving another agent’s exclusive reservation, provided the repository runs scripts from those hook directories.

Setup and configuration

Installation requires Bun 1.4.2 or newer. Supported operating environments are Linux with systemd and Windows 10 or 11; WSL 2 with systemd enabled counts as Linux. macOS is not currently supported. The project provides separate setup scripts: scripts/enable.sh builds the binary and starts a Linux user service, while scripts/enable-windows.ts creates a Windows executable and a per-logon scheduled task.

The database is stored at ~/.local/share/swarmail/mail.sqlite3. After starting the service, scripts/configure-mcp.ts registers it with supported host configurations found under the user’s home directory. A dry-run option previews changes. On WSL, the script can also register Windows-side hosts against the same server.

configure-hooks.ts installs registration hooks for installed hosts, wake hooks for Claude Code and Cursor, and a Claude Code Swarmail modification unless disabled. Codex requires the registration hook to be trusted once in its hooks settings. Wake bridges are optional foreground processes and are not started by installation.

An MCP client that only supports stdio or installs servers from a registry can run npx -y swarmail-mcp. That relay forwards requests to the already-running local service rather than starting a second server or installing the application itself.

Tools and capabilities

The Swarmail MCP server supports:

• Registering an agent session and reading its inbox.
• Sending new messages and replying in existing threads.
• Fetching and acknowledging unread mail.
• Searching messages with full-text search.
• Creating and checking advisory file reservations.
• Listing agents associated with a repository through the command line.
• Delivering mail to supported host sessions through hooks and opt-in bridges.

Configured host support covers Claude Code, Codex, Cursor, Grok, Antigravity, Devin, and OpenCode. Claude Code and Cursor can wake on incoming mail. Cursor, Devin, and Antigravity can receive mail during active work through native hooks, while configured bridges also support explicit T3 Code, OpenCode, native Codex, and native Grok targets with steering.

Limitations and notes

This is intended for coordination on one machine, not authenticated remote messaging. Run either the WSL or native Windows server, not both, because both use port 18765 and mirrored WSL networking shares that port with Windows. Native Windows support is described as a preview, with some wake and logon scenarios not yet verified.

Hook behavior depends on each host’s configuration and shell environment. On Windows, paths with spaces or non-ASCII characters can require short-name handling, and Cursor’s PowerShell 5.1 input path can mangle non-ASCII repository paths. The guard only works when the repository’s existing pre-commit and pre-push hooks execute scripts from the installed directories.