mcp_agent_mail_rust
Rust MCP server for multi-agent coordination: 34 tools, Git-backed archive, SQLite indexing, advisory file locks, and an interactive TUI console
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Dicklesworthstone/mcp_agent_mail_rust with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Dicklesworthstone/mcp_agent_mail_rust'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/dicklesworthstone--mcp-agent-mail-rust)HTML
<a href="/listings/dicklesworthstone--mcp-agent-mail-rust"><img src="/api/listings/dicklesworthstone--mcp-agent-mail-rust/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
One-Liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.sh?$(date +%s)" | bash
Downloads the right binary for your platform, installs to `~/.local/bin`, optionally updates your `PATH`, and auto-configures detected Codex CLI configs for HTTP MCP URL mode. Downloaded release archives are verified **before extraction by default**. The requested version is normalized to the release tag `vX.Y.Z` (or `vX.Y.Z-prerelease`), and the trust model depends on the release generation:
- **Releases v0.3.31 and later** (the current model): releases are built and published by the maintainer's own release infrastructure rather than GitHub Actions, and every release ships a `SHA256SUMS` manifest plus a detached **minisign** signature (`SHA256SUMS.minisig`) made with the maintainer-held release key (id `1BBD79B28BF718D0`; the public key is pinned inside the installer). The installer verifies the signature over the exact manifest bytes with `minisign`, then verifies the archive's SHA-256 against the authenticated manifest. A missing `minisign` executable, manifest, signature, or checksum entry aborts the install; `cosign` is not required or consulted for these releases. This replaced the earlier keyless GitHub-Actions Sigstore requirement, which had become unsatisfiable once releases stopped being built by Actions — the trust anchor is now a key the maintainer controls (the same model as the maintainer's other released tools), and verification remains fail-closed. `am self-update` applies the same model with a built-in minisign verifier (the release public key is embedded in the binary; no `minisign` executable is needed) and refuses unsigned or tampered manifests. See [SECURITY.md](SECURITY.md#release-trust-model). - **Releases before v0.3.31** (legacy): the installer requires a SHA-256 witness plus a non-empty modern Sigstore bundle that `cosign` validates against the literal workflow identity `https://github.com/Dicklesworthstone/mcp_agent_mail_rust/.github/workflows/dist.yml@refs/tags/<requested-tag>` and OIDC issuer `https://token.actions.githubusercontent.com`, so a valid archive and bundle from any other tag are rejected. A stable `cosign` **v3.1.3 or newer in the v3 line** must be on `PATH`; older versions are rejected because of [GHSA-fx35-mq7g-6g98](https://github.com/sigstore/cosign/security/advisories/GHSA-fx35-mq7g-6g98), and v4 is not accepted until its verifier contract is reviewed. Verification forces the modern bundle parser and ignores caller-supplied `SIGSTORE_ROOT_FILE`, `SIGSTORE_REKOR_PUBLIC_KEY`, and `SIGSTORE_CT_LOG_PUBLIC_KEY_FILE` overrides.
In both models, a missing checksum, SHA-256 implementation, signature witness, or required verifier executable—and any malformed or mismatched signature evidence—aborts the install.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 2,451 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # MCP Agent Mail (Rust)
- <div align="center">
- <img src="docs/assets/am_illustration.webp" alt="MCP Agent Mail - A mail-like coordination layer for AI coding agents">
- </div>
- <div align="center">
- [](./LICENSE)
- </div>
- > "It's like Gmail for your coding agents!"
- A mail-like coordination layer for AI coding agents, exposed as an MCP server with 45 tools and 25 resources, Git-backed archive, SQLite indexing, an interactive 16-screen TUI, a server-rendered web UI, and an agent-first robot CLI. The Rust rewrite of the [original Python project](https://github.com/Dicklesworthstone/mcp_agent_mail) (1,700+ stars).
- **Supported agents:** [Claude Code](https://claude.ai/code), [Codex CLI](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Oh My Pi (OMP)](https://omp.sh), [GitHub Copilot CLI](https://docs.github.com/en/copilot), and any MCP-compatible client.
- Watch the [23-minute walkthrough](https://youtu.be/68VVcqMEDrs) to see seven AI coding agents send over 1,000 messages to each other while implementing a development plan over two days.
- <div align="center">
- <h3>Quick Install</h3>
- ```bash
- curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.sh?$(date +%s)" | bash
- ```
- <p><em>Works on Linux and macOS (x86_64 and aarch64). Auto-detects your platform, downloads the right binary, and configures detected coding agents for HTTP MCP.</em></p>
- <p><em>Needs <code>minisign</code> on <code>PATH</code> to verify the release (and <code>xz</code> on minimal Linux images); see <a href="#one-liner-recommended">One-Liner</a>.</em></p>
- </div>
- ---
- ## Table of Contents
- - [TL;DR](#tldr)
- - [Why This Exists](#why-this-exists)
- - [What People Are Saying](#what-people-are-saying)
- - [Design Philosophy](#design-philosophy)
- - [Rust vs. Python: Stress Test Results](#rust-vs-python-stress-test-results)
- - [Installation](#installation)
- - [Quick Start](#quick-start)
- - [Agent Configuration](#agent-configuration)
- - [Server Modes](#server-modes)
- - [Operator CLI Surface](#operator-cli-surface)
- - [The 45 MCP Tools](#the-45-mcp-tools)
- - [TUI Operations Console](#tui-operations-console)
- - [Robot Mode (`am robot`)](#robot-mode-am-robot)
- - [File Reservations](#file-reservations-for-multi-agent-editing)
- - [Multi-Agent Coordination Workflows](#multi-agent-coordination-workflows)
- - [Web UI](#web-ui)
- - [Deployment Validation](#deployment-validation)
- - [Configuration](#configuration)
- - [Architecture](#architecture)
- - [ATC Learning Implementation Map](#atc-learning-implementation-map)
- - [Core Data Model](#core-data-model)
- - [How the System Works](#how-the-system-works)
- - [Search Architecture](#search-architecture)
- - [Coordination Algorithms and Safety Invariants](#coordination-algorithms-and-safety-invariants)
- - [Consistency and Recovery Model](#consistency-and-recovery-model)
- - [Comparison vs. Alternatives](#comparison-vs-alternatives)
- - [Development](#development)
- - [Performance and Benchmarking](#performance-and-benchmarking)
- - [Mailbox Diagnostics (`am doctor`)](#mailbox-diagnostics-am-doctor)
- - [Troubleshooting](#troubleshooting)
- - [Limitations](#limitations)
- - [FAQ](#faq)
- - [Appendix: Protocol Transcript](#appendix-protocol-transcript)
- - [Appendix: TUI vs. Web vs. Robot](#appendix-tui-vs-web-vs-robot)
- - [Documentation](#documentation)
- - [About Contributions](#about-contributions)
- - [License](#license)
- ---
- ## TL;DR
- **The Problem**: Modern projects often run multiple coding agents at once (backend, frontend, scripts, infra). Without a shared coordination fabric, agents overwrite each other's edits, miss critical context from parallel workstreams, and require humans to relay messages across tools and teams.
- **The Solution**: Agent Mail gives every coding agent a persistent identity (e.g., `GreenCastle`), an inbox/outbox, searchable threaded conversations, and advisory file reservations (leases) to signal editing intent. Everything is backed by Git for human-auditable artifacts and SQLite for fast indexing and search.
- ### Why Use Agent Mail?
- | Feature | What It Does |
- |---------|--------------|
- | **Advisory File Reservations** | Agents declare exclusive or shared leases on file globs before editing, preventing conflicts with a pre-commit guard |
- | **Asynchronous Messaging** | Threaded inbox/outbox with subjects, CC/BCC, acknowledgments, and importance levels |
- | **Token-Efficient** | Messages stored in a per-project archive, not in agent context windows |
- | **25 MCP Resources** | Read-only inbox, thread, reservation, tooling, identity, and attention views for cheap lookups |
- | **45 MCP Tools** | Infrastructure, identity, messaging, contacts, reservations, search, macros, product bus, and build slots |
- | **16-Screen TUI** | Live operator cockpit for messages, threads, agents, search, reservations, metrics, health, analytics, attachments, archive browsing, and ATC |
- | **Web UI** | Server-rendered `/mail/` routes for human oversight, unified inbox review, search, attachments, and overseer messaging |
- | **Robot Mode** | 19 agent-optimized CLI subcommands with `toon`/`json` output (`md` for thread and message views) for non-interactive workflows |
- | **Git-Backed Archive** | Every message, reservation, and agent profile stored as files in per-project Git repos |
- | **Hybrid Search** | Portable lexical Search V3 uses the local Tantivy bridge. Optional FrankenSearch integration supplies semantic and hybrid routing in builds with the `hybrid` feature and the runtime opt-in `AM_SEARCH_SEMANTIC_ENABLED=true`. Without both, every query runs lexical. |
- | **Pre-Commit Guard** | Git hook that blocks commits touching files reserved by other agents |
- | **Dual-Mode Interface** | MCP server (`mcp-agent-mail`) and operator CLI (`am`) share tools but enforce strict surface separation |
- ### Quick Example
- ```bash
- # Start the server (the installer already configured your detected coding agents;
- # `am setup run` re-runs that setup at any time)
- am
- # That's it. Server starts on 127.0.0.1:8765 with the interactive TUI.
- # Agents coordinate through MCP tools:
- # ensure_project(human_key="/abs/path")
- # register_agent(project_key="/abs/path", program="claude-code", model="opus-4.6")
- # file_reservation_paths(project_key="/abs/path", agent_name="BlueLake", paths=["src/**"], ttl_seconds=3600, exclusive=true)
- # send_message(project_key="/abs/path", sender_name="BlueLake", to=["GreenCastle"], subject="Starting refactor", body_md="Taking src/**", thread_id="FEAT-123")
- # fetch_inbox(project_key="/abs/path", agent_name="BlueLake")
- # Or use the robot CLI for non-interactive agent workflows:
- am robot status --project /abs/path --agent BlueLake
- am robot inbox --project /abs/path --agent BlueLake --urgent --format json
- am robot reservations --project /abs/path --agent BlueLake --conflicts
- ```
- ### What Agent Conversations Look Like
- Example exchange between two agents coordinating a refactor:
- ```
- ┌──────────────────────────────────────────────────────────────────────────────┐
- │ Thread: FEAT-123 - Auth module refactor │
- ├──────────────────────────────────────────────────────────────────────────────┤
- │ │
- │ ┌──────────────────────────────────────────────────────────────────────────┐ │
- │ │ GreenCastle -> BlueLake 2026-02-16 10:03 │ │
- │ │ Subject: Starting auth refactor │ │
- │ ├──────────────────────────────────────────────────────────────────────────┤ │
- │ │ I'm reserving src/auth/** for the next hour. Can you focus on the API │ │
- │ │ tests in tests/api/** instead? │ │
- │ │ [ack_required: true] │ │
- │ └──────────────────────────────────────────────────────────────────────────┘ │
- │ │
- │ ┌──────────────────────────────────────────────────────────────────────────┐ │
- │ │ BlueLake -> GreenCastle 2026-02-16 10:04 │ │
- │ │ Subject: Re: Starting auth refactor │ │
- │ ├──────────────────────────────────────────────────────────────────────────┤ │
- │ │ Confirmed. Releasing my reservation on src/auth/** and taking │ │
- │ │ tests/api/** exclusively. Will sync when I hit the auth middleware │ │
- │ │ boundary. │ │
- │ │ [ack: OK] │ │
- │ └──────────────────────────────────────────────────────────────────────────┘ │
- │ │
- │ ┌──────────────────────────────────────────────────────────────────────────┐ │
- │ │ BlueLake -> GreenCastle 2026-02-16 10:31 │ │
- │ │ Subject: Re: Starting auth refactor │ │
- │ ├──────────────────────────────────────────────────────────────────────────┤ │
- │ │ Found a broken assertion in tests/api/auth_test.rs:142 -- the expected │ │
- │ │ token format changed. Heads up if you're touching the JWT issuer. │ │
- │ └──────────────────────────────────────────────────────────────────────────┘ │
- │ │
- │ ┌──────────────────────────────────────────────────────────────────────────┐ │
- │ │ GreenCastle -> BlueLake 2026-02-16 10:33 │ │
- │ │ Subject: Re: Starting auth refactor │ │
- │ ├──────────────────────────────────────────────────────────────────────────┤ │
- │ │ Good catch. I just changed the claims struct. Updated the test fixture │ │
- │ │ in my commit. Releasing src/auth/** now -- all yours if you need it. │ │
- │ └──────────────────────────────────────────────────────────────────────────┘ │
- │ │
- └──────────────────────────────────────────────────────────────────────────────┘
- ```
- No human relay needed. Agents negotiate file ownership, flag breaking changes in real time, and hand off work through structured, threaded messages stored in Git.
- ---
- ## Why This Exists
- Modern projects often run multiple coding agents at once (backend, frontend, scripts, infra). Without a shared coordination fabric, agents overwrite each other's edits, miss critical context from parallel workstreams, and require humans to relay messages across tools and teams.
- Agent Mail has been available since October 2025 and was designed around real multi-agent coding workloads across providers such as Claude Code, Codex CLI, and Gemini CLI. The adjacent [Beads](https://github.com/Dicklesworthstone/beads_rust) and [bv](https://github.com/Dicklesworthstone/beads_viewer) tools make it more useful as a full coordination stack: Beads tracks work, bv helps pick the right next work, and Agent Mail carries the coordination traffic.
- ### The Footguns Agent Mail Avoids
- **No "broadcast to all" mode.** Given the option, many agents will overuse broadcast-style messaging. That is the equivalent of default reply-all in email: lots of irrelevant noise and wasted context.
- **Carefully refined API ergonomics.** Bad MCP documentation and poor agent ergonomics quietly wreck reliability. Agent Mail's 45 tool definitions have gone through repeated real-world iteration so they work predictably without wasting tokens.
- **No git worktrees.** Worktrees can slow development velocity and create reconciliation debt when agents diverge. Agent Mail takes the opposite approach: keep agents in one shared space, surface conflicts quickly, and give them tools to coordinate through them.
- **Advisory file reservations instead of hard locks.** For this problem, advisory reservations fit better than hard locks. Agents can temporarily claim files while they work, reservations expire automatically, and stale claims can be reclaimed. That makes the system robust to crashed or reset agents; hard locks would not.
- **Semi-persistent identity.** An identity that can last for the duration of a discrete task (for the purpose of coordination), but one that can also vanish without a trace and not break things. You don't want ringleader agents whose death takes down the whole system. Agent Mail identities are memorable (e.g., `GreenCastle`), but ephemeral by design.
- **Graph-aware task selection.** If you have 200-500 tasks, you don't want agents randomly choosing them or wasting context communicating about what to do. There's usually a "right answer" for what each agent should work on, and that right answer comes from the dependency structure of the tasks. That's what [bv](https://github.com/Dicklesworthstone/beads_viewer) computes using graph theory, like a compass that tells each agent which direction will unlock the most work overall.
- ### What Agent Mail Gives You
- - **Prevents conflicts:** Explicit file reservations (leases) for files/globs prevent agents from overwriting each other
- - **Reduces human relay work:** Agents send messages directly to each other with threaded conversations, acknowledgments, and priority levels
- - **Keeps communication off the token budget:** Messages stored in per-project Git archive, not consuming agent context windows
- - **Offers quick reads:** `resource://inbox/{Agent}?project=<abs-path>`, `resource://thread/{id}?project=<abs-path>`, and 23 other MCP resources
- - **Provides full audit trails:** Every instruction, lease, message, and attachment is in Git for human review
- - **Scales across repos:** Frontend and backend agents in different repos coordinate through the product bus and contact system
- ### Typical Use Cases
- - Multiple agents splitting a large refactor across services while staying in sync
- - Frontend and backend agent teams coordinating thread-by-thread across repositories
- - Protecting critical migrations with exclusive file reservations and pre-commit guards
- - Searching and summarizing long technical discussions as threads evolve
- - Running agent swarms with [Beads](https://github.com/Dicklesworthstone/beads_rust) task tracking for dependency-aware work selection
- ### Productivity Math
- Parallel agent work changes the economics of supervision. One human operator can spend an hour steering several agents while those agents produce many hours of implementation work in parallel. The exact multiplier depends on the task and on how disciplined the workflow is, but the point is straightforward: coordination overhead matters, and Agent Mail is built to keep that overhead low.
- ---
- ## What People Are Saying
- > "Agent Mail and Beads feel like the first 'agent-native' tooling."
- > — [@jefftangx](https://x.com/jefftangx/status/1998100767698506047)
- > "Agent mail is a truly brain-melting experience the first time. Thanks for building it."
- > — [@quastora](https://x.com/quastora/status/2001130619481502160)
- > "Between Claude Code, Codex CLI, and Gemini; Beads; and Agent Mail — basically already 80% the way to the autonomous corporation. It blows my mind this all works now!"
- > — [@curious_vii](https://x.com/curious_vii/status/2000315148410695927)
- > "Use it with agent mail == holy grail."
- > — [@metapog](https://x.com/metapog/status/1995323125790089251)
- > "The only correct answer to this is mcp agent mail."
- > — [@skillcreatorai](https://x.com/skillcreatorai/status/2006099437144199479)
- > "GPT 5.2 suggesting beads + agent mail for agent co-ordination (of course, I am already using them)."
- > — [@jjpcodes](https://x.com/jjpcodes/status/1999778297488826542)
- ---
- ## Design Philosophy
- **Mail metaphor, not chat.** Agents send discrete messages with subjects, recipients, and thread IDs. Work coordination is structured communication with clear intent, not a firehose. Imagine if your email system at work defaulted to reply-all every time; that's what chat-based coordination does, and it burns context fast.
- **SQLite for live state, Git for the durable ledger.** The accepted write path mutates SQLite first so inboxes, resources, TUI, web, and robot views see one fresh operational state. The same write then emits human-readable message, profile, and reservation artifacts into the per-project Git archive for audit and recovery.
- **Advisory, not mandatory.** File reservations are advisory leases, not hard locks. The pre-commit guard enforces them at commit time, but agents can override if needed. Acquiring a reservation reports conflicts instead of waiting for another agent to release its lease. Reservations expire on a TTL; they do not prevent deadlocks in the storage or runtime layers.
- **Resilient to agent death.** Agents die all the time: context windows overflow, sessions crash, memory gets wiped. Any agent can vanish without breaking the system. No ringleader agents, no single points of failure. Semi-persistent identities exist for coordination but don't create hard dependencies.
- **Dual persistence.** Human-readable Markdown in Git for auditability; SQLite for live indexing plus Search V3 for fast lexical/semantic retrieval. Both stay in sync through the write pipeline.
- **Structured concurrency, no Tokio.** The entire async stack uses [asupersync](https://github.com/Dicklesworthstone/asupersync) with `Cx`-threaded structured concurrency. No orphan tasks, cancel-correct channels, and deterministic testing with virtual time.
- ---
- ## Rust vs. Python: Stress Test Results
- The Python implementation had three recurring failure modes under real multi-agent workloads: Git lock file contention from concurrent writes, SQLite pool exhaustion under sustained load, and cascading failures when many agents hit the server simultaneously. The Rust rewrite addresses these through batching, bounded pools, and backpressure. The measurements below are retained results from the original stress campaign, not a passing verdict for the current release candidate or a guarantee for every workload (the heavy multi-agent stress tests in `crates/mcp-agent-mail-storage/tests/stress_pipeline.rs` are marked `#[ignore]` for explicit `-- --ignored` stress runs and currently enforce a 120s release-host ceiling, measured at 38–47s after durable archive-fsync hardening).
- ### The 10-Test Gauntlet
- | Test | Result | Key Metrics |
- |------|--------|-------------|
- | 30-agent message pipeline | PASS | 150/150 success, p99=6.8s, 0 errors |
- | 10-project concurrent ops | PASS | 150/150 success, 0 errors |
- | Commit coalescer batching | PASS | 9.1x batching ratio (100 writes → 11 commits) |
- | Stale git lock recovery | PASS | Lock detected, cleaned, writes resumed |
- | Mixed reservations + messages | PASS | 80+80 ops, 0 errors |
- | WBQ saturation | PASS | 2000/2000 enqueued, 0 errors, 0 fallbacks |
- | Pool exhaustion (60 threads, pool=15) | PASS | 600/600 success, 0 timeouts, 24 ops/sec |
- | Sustained 30s mixed workload | PASS | 1494 ops, ~49 RPS, p99=2.6s, 0 errors |
- | Thundering herd (50 threads, 1 agent) | PASS | All 50 got same ID, 0 errors |
- | Inbox reads during message storm | PASS | 150 sends + 300 reads, 0 errors |
- ### Python Problem → Rust Fix
- | Python Failure Mode | What the Rust Tests Exercise | Result |
- |---------------------|------------------------------|--------|
- | **Git lock file contention** | Commit coalescer batching (100 concurrent writes → 11 commits, 9.1x reduction), stale lock recovery, multi-project isolation | 0 lock errors |
- | **SQLite pool exhaustion** | 60 threads on pool of 15, sustained 50 RPS for 30s, thundering herd (50 threads → 1 agent) | 0 timeouts, 0 DB errors |
- | **Overloading with many agents** | 30 agents × 5 messages, 10 projects × 5 agents, 2000 WBQ operations, mixed reservation+message workload | 0 errors across all |
- ### What Makes the Difference
- - **Fewer Git lock acquisitions.** The commit coalescer batches rapid-fire writes into fewer git commits (9.1x reduction in the recorded run). Git plumbing commits avoid `index.lock` in the normal archive path; other Git operations can still contend.
- - **Pool exhaustion handled gracefully.** Even with 4x more threads than pool connections (60 vs 15), all 600 operations succeeded with 0 timeouts. WAL mode + a bounded 20s `busy_timeout` lets writers queue rather than fail (and give up before the 30s client deadline).
- - **Stale lock recovery works.** Crashed-process lock files are detected via PID checking and cleaned up automatically, so a dead agent never holds the archive hostage.
- - **Write-behind queue backpressure is clean.** 2000 rapid-fire enqueues from 20 threads — all accepted with 0 fallbacks or errors.
- - **Read/write concurrency is solid.** Concurrent inbox reads and message writes produce 0 errors. WAL mode allows unlimited readers alongside writers.
- The stress tests live in `crates/mcp-agent-mail-storage/tests/stress_pipeline.rs` (Rust unit tests targeting the DB+Git pipeline) and `tests/e2e/test_stress_load.sh` (HTTP E2E tests hammering a live server through the full network→server→DB→git pipeline).
- ---
- ## Installation
- ### One-Liner (recommended)
- ```bash
- curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.sh?$(date +%s)" | bash
- ```
- **Prerequisites:** the installer verifies the release with `minisign` and refuses to install without it, and minimal Linux images also lack `xz`. macOS: `brew install minisign`. Debian 12+ and Ubuntu 24.04+: `apt install minisign xz-utils`. Ubuntu 22.04 and Debian 10 have no `minisign` package: use the static binary from the [minisign releases](https://github.com/jedisct1/minisign/releases).
- Downloads the right binary for your platform, installs to `~/.local/bin`, optionally updates your `PATH`, and auto-configures detected Codex CLI configs for HTTP MCP URL mode. Downloaded release archives are verified **before extraction by default**. The requested version is normalized to the release tag `vX.Y.Z` (or `vX.Y.Z-prerelease`), and the trust model depends on the release generation:
- - **Releases v0.3.31 and later** (the current model): releases are built and published by the maintainer's own release infrastructure rather than GitHub Actions, and every release ships a `SHA256SUMS` manifest plus a detached **minisign** signature (`SHA256SUMS.minisig`) made with the maintainer-held release key (id `1BBD79B28BF718D0`; the public key is pinned inside the installer). The installer verifies the signature over the exact manifest bytes with `minisign`, then verifies the archive's SHA-256 against the authenticated manifest. A missing `minisign` executable, manifest, signature, or checksum entry aborts the install; `cosign` is not required or consulted for these releases. This replaced the earlier keyless GitHub-Actions Sigstore requirement, which had become unsatisfiable once releases stopped being built by Actions — the trust anchor is now a key the maintainer controls (the same model as the maintainer's other released tools), and verification remains fail-closed. `am self-update` applies the same model with a built-in minisign verifier (the release public key is embedded in the binary; no `minisign` executable is needed) and refuses unsigned or tampered manifests. See [SECURITY.md](SECURITY.md#release-trust-model).
- - **Releases before v0.3.31** (legacy): the installer requires a SHA-256 witness plus a non-empty modern Sigstore bundle that `cosign` validates against the literal workflow identity `https://github.com/Dicklesworthstone/mcp_agent_mail_rust/.github/workflows/dist.yml@refs/tags/<requested-tag>` and OIDC issuer `https://token.actions.githubusercontent.com`, so a valid archive and bundle from any other tag are rejected. A stable `cosign` **v3.1.3 or newer in the v3 line** must be on `PATH`; older versions are rejected because of [GHSA-fx35-mq7g-6g98](https://github.com/sigstore/cosign/security/advisories/GHSA-fx35-mq7g-6g98), and v4 is not accepted until its verifier contract is reviewed. Verification forces the modern bundle parser and ignores caller-supplied `SIGSTORE_ROOT_FILE`, `SIGSTORE_REKOR_PUBLIC_KEY`, and `SIGSTORE_CT_LOG_PUBLIC_KEY_FILE` overrides.
- In both models, a missing checksum, SHA-256 implementation, signature witness, or required verifier executable—and any malformed or mismatched signature evidence—aborts the install.
- Options: `--version vX.Y.Z`, `--dest DIR`, `--system` (installs to `/usr/local/bin`), `--from-source`, `--verify` (run an additional post-install self-test), `--no-verify` (**unsafe** explicit escape that skips the checksum and signature checks), `--easy-mode` (auto-update PATH), `--force`, `--no-service` (never install/modify/restart the background service; also implied automatically by a non-default `--dest`), `--uninstall`, `--yes`, `--purge`. **`--no-verify` allows unauthenticated downloaded binaries to execute during mandatory version probes before installation; malicious archive bytes can therefore run arbitrary code as the installer user.** Archive verification applies to downloaded release archives, not source builds. Every downloaded archive must contain the two expected flat, non-empty regular-file binaries and may also contain flat regular-file `README.md` and `LICENSE` entries; duplicate or other members are rejected. Both staged binaries and both installed binaries must report the exact requested version. Those member/version checks are mandatory even with `--no-verify`; the flag also does not disable the optional broader `--verify` post-install self-test. A failed archive download never silently changes into a source build. Explicit `--from-source` checks out the exact requested tag, uses its Cargo.lock for `cargo build --locked`, and subjects the staged and installed pair to the same exact-version and byte-preserving transactional replacement gates.
- A successful source install prints the path of a mode-private `source-receipt` retained inside its committed transaction-history directory. The hash-witnessed receipt binds the normalized release tag, exact Agent Mail commit, Cargo.lock SHA-256, and both installed binary SHA-256 digests. Cargo resolves external dependencies from the tagged lockfile; the installer verifies that its digest stays unchanged through the locked build. Source installation does not fetch unused sibling repositories. Tags with external path dependencies are refused before compilation. Interrupted or rolled-back transactions retain their evidence under an explicitly non-committed history name and are never reported as installed source provenance.
- Source builds also require working Python 3 or Perl with `JSON::PP` to verify dependency metadata. Every local path dependency must resolve inside the tagged checkout; an external path or symlink escape is refused before compilation. Registry and Git dependencies remain governed by Cargo.lock.
- ### Windows One-Liner (PowerShell)
- ```powershell
- iwr -useb "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.ps1?$(Get-Random)" | iex
- ```
- PowerShell enforces the same per-release trust contract before `Expand-Archive`: for releases v0.3.31 and later it verifies the minisign-signed `SHA256SUMS` manifest with the same pinned maintainer key (a `minisign` executable on `PATH` is required; `cosign` is not consulted), and for older releases it requires the same stable `cosign` v3.1.3-or-newer-in-v3 verifier, forces modern-bundle parsing, and isolates verification from the three custom Sigstore trust environment variables named above. The ZIP must contain `am.exe` and `mcp-agent-mail.exe`, with optional `README.md` and `LICENSE` entries. Every member must be a flat, non-empty regular file; duplicate or other members are rejected. The binaries' staged and post-install version lines must exactly match the requested release. Both executables are replaced under one per-destination installer mutex and rollback domain; backups remain until byte-for-byte installed-digest and version checks pass. Options: `-Version vX.Y.Z`, `-Dest PATH`, `-Force`, `-Verify` (explicitly request the already-default cryptographic checks), and `-NoVerify` (the **unsafe** escape that skips only those checksum and signature checks). Archive-member and exact-version checks still run with `-NoVerify`, which means unauthenticated downloaded executables run during version probes and may execute arbitrary code as the installer user.
- ### Container (Docker or Podman)
- Each release also publishes a `linux/amd64` + `linux/arm64` image to GHCR, tagged `vX.Y.Z`, `X.Y.Z`, `0.3` and `latest`:
- ```bash
- docker run -d --name agent-mail -p 127.0.0.1:8765:8765 \
- -e HTTP_BEARER_TOKEN="$(openssl rand -hex 32)" \
- -v agent-mail-data:/data/mailbox \
- ghcr.io/dicklesworthstone/mcp_agent_mail_rust:latest
- ```
- The image runs `mcp-agent-mail serve --no-tui` as the non-root `appuser`, serving MCP on port 8765 at `/mcp/`, with the whole mailbox (Git archive and SQLite) under `/data/mailbox`. Mount a volume there so mail survives replacing the container. Every request needs the token (`Authorization: Bearer <token>`); clients connect to `http://127.0.0.1:8765/mcp/` with it. Keep the published port on loopback unless remote agents should reach it. Docker's healthcheck polls `/health/liveness`. The image packages the release's Linux glibc binaries unchanged ([`Dockerfile.release`](Dockerfile.release)).
- For a local source image, resolve the revision before building and tag the
- result by both the source commit and its image ID. A rebuild that produces
- different bytes receives a different tag. Run these commands from the checkout
- with Docker Buildx installed. The selected commit must be fetchable from the
- project's GitHub repository.
- ```bash
- revision=$(git rev-parse --verify 'HEAD^{commit}')
- build_dir=$(mktemp -d)
- BUILDX_METADATA_PROVENANCE=max docker buildx build \
- --file Dockerfile --build-arg "AM_REF=$revision" \
- --load --iidfile "$build_dir/image-id" \
- --metadata-file "$build_dir/build-metadata.json" "$build_dir" &&
- image_id=$(cat "$build_dir/image-id") &&
- docker image tag "$image_id" "mcp-agent-mail-rust:source-$revision-${image_id#sha256:}"
- ```
- The resulting image exposes its commit in `org.opencontainers.image.revision`.
- It also records the Cargo lockfile and Rust toolchain file digests in
- `/usr/share/mcp-agent-mail/source-provenance`.
- `build-metadata.json` records the Dockerfile bytes and image config digest.
- [BuildKit metadata reference](https://docs.docker.com/reference/cli/docker/buildx/build/#metadata-file)
- ### From Source
- ```bash
- git clone https://github.com/Dicklesworthstone/mcp_agent_mail_rust
- cd mcp_agent_mail_rust
- ./install-local.sh # builds release, installs to ~/.local/bin
- # DEST=/usr/local/bin ./install-local.sh # custom destination
- ```
- The script resolves the correct Cargo target directory via `cargo metadata`, so the
- installed binary always matches the freshly-built artifact regardless of
- `CARGO_TARGET_DIR` overrides or workspace settings. Do **not** manually copy from
- `target/release/am` -- if `CARGO_TARGET_DIR` is set, that path may be stale.
- Requires Rust nightly (see `rust-toolchain.toml`). Current `main` records [FrankenSearch](https://github.com/Dicklesworthstone/frankensearch) 0.6.1 at revision `616c9a7a6bdada97d81f760808996911ba3be294` in `Cargo.toml` and `Cargo.lock`, aligned with `FRANKENSEARCH_COMMIT` in `.github/workflows/dist.yml`. This optional `hybrid` integration shares FastMCP's rustix 1.1.5 requirement and enables local Model2Vec and native reranking without FastEmbed or Tokio. Portable builds use the local Tantivy bridge for lexical Search V3 without enabling FrankenSearch integration.
- A manual build, source installation, and the release build recipes need no FrankenSearch, fast_cmaes, or Beads sibling checkout. Use `cargo build --locked` to retain the checked-in dependency graph. Source-install receipts record that lockfile's digest alongside the exact source commit and binary pair.
- The mailbox uses FrankenSQLite `=0.4.13` through SQLModel 0.5.1 on Asupersync 0.5.0. Only `fsqlite-core` is patched to [revision `e7ffeff4`](https://github.com/Dicklesworthstone/frankensqlite/commit/e7ffeff4eb1eda0a4d62d00bbe778d6103058e7f) to keep archive headers and rows on one transaction and recover bounded zero-filled WAL certificate tails, including false EOF boundaries; its package version is 0.4.14, while the other 19 engine packages remain registry 0.4.13.
- SQLModel's pool, core and FrankenSQLite driver are pinned to [revision `ca959f89`](https://github.com/Dicklesworthstone/sqlmodel_rust/commit/ca959f899b98fbea7af19e942e687dae9b71f258) for cancellation-safe waiter cleanup, cooperative acquisition deadlines and synchronous SQLite connection retirement; published 0.5.1 lacks these fixes. Synchronous driver work must still yield for a deadline to interrupt it.
- Asupersync is pinned to [revision `2946438a`](https://github.com/Dicklesworthstone/asupersync/commit/2946438a5d2bd164c9aee73a5ea079afe0c13907) so malformed HTTP request heads receive an error response before the connection closes; registry 0.5.0 silently drops those connections. This revision also includes the upstream resume-factory Send fix and keeps all consumers on one 0.5 runtime type graph. No sibling checkout is needed for these patches.
- `Cargo.lock` selects the FastMCP 0.13.0 family from crates.io, with `fastmcp-rust` imported as `fastmcp`. Beads discovery and queries use the installed `br` CLI; discovery runs its database-free config-path command, and Agent Mail no longer embeds a second storage engine. See [`UPGRADE_LOG.md`](UPGRADE_LOG.md) for engine qualification results. If persisted tool metrics have already bloated your mailbox, stop the server and follow the [offline recovery procedure](docs/RECOVERY_RUNBOOK.md) before running `am doctor vacuum --yes`; upgrading does not compact existing pages.
- ### Platforms
- | Platform | Architecture | Binary |
- |----------|-------------|--------|
- | Linux | x86_64 (static; the installer's default) | `mcp-agent-mail-x86_64-unknown-linux-musl` |
- | Linux | x86_64 (glibc 2.28+) | `mcp-agent-mail-x86_64-unknown-linux-gnu` |
- | Linux | aarch64 | `mcp-agent-mail-aarch64-unknown-linux-gnu` |
- | macOS | x86_64 | `mcp-agent-mail-x86_64-apple-darwin` |
- | macOS | Apple Silicon | `mcp-agent-mail-aarch64-apple-darwin` |
- | Windows | x86_64 | `mcp-agent-mail-x86_64-pc-windows-msvc.zip` |
- ---
- ## Quick Start
- ### 1. Start the server
- ```bash
- am
- ```
- Starts the HTTP server on `127.0.0.1:8765` with the interactive TUI. It leaves existing MCP client configuration untouched: the curl installer configures detected coding agents (Claude Code, Codex CLI, Gemini CLI, OMP, etc.), and `am setup run` (or `am serve-http --setup`) configures them explicitly afterwards.
- ### 2. Agents register and coordinate
- Once the server is running, agents use MCP tools to coordinate:
- Terminology note: `ensure_project` takes a `human_key`, which must be the absolute repo path. Most follow-on tools take `project_key`, which can be that same absolute path or the project's computed slug.
- ```
- # Register identity
- ensure_project(human_key="/abs/path/to/repo")
- register_agent(project_key="/abs/path/to/repo", program="claude-code", model="opus-4.6")
- # Reserve files before editing
- file_reservation_paths(project_key="/abs/path/to/repo", agent_name="GreenCastle", paths=["src/**"], ttl_seconds=3600, exclusive=true)
- # Send a message
- send_message(project_key="/abs/path/to/repo", sender_name="GreenCastle", to=["BlueLake"],
- subject="Starting auth refactor", body_md="Taking src/auth/**",
- thread_id="FEAT-123", ack_required=true)
- # Check inbox
- fetch_inbox(project_key="/abs/path/to/repo", agent_name="BlueLake")
- acknowledge_message(project_key="/abs/path/to/repo", agent_name="BlueLake", message_id=123)
- ```
- ### 3. Use macros for common flows
- ```
- # Boot a full session (ensure project + register agent + reserve files + fetch inbox)
- macro_start_session(human_key="/abs/path/to/repo", program="claude-code", model="opus-4.6")
- # Prepare for a thread (fetch context + recent messages)
- macro_prepare_thread(project_key="/abs/path/to/repo", thread_id="FEAT-123",
- program="claude-code", model="opus-4.6")
- # Reserve, work, release cycle
- macro_file_reservation_cycle(project_key="/abs/path/to/repo", agent_name="GreenCastle",
- paths=["src/auth/**"], ttl_seconds=3600, auto_release=true)
- # Contact handshake between agents in different projects: approves the link and
- # delivers the welcome into the target's project (without auto_accept the link
- # stays pending, no welcome is sent, and the response says why; auto_accept never
- # overrides a link the target has blocked)
- macro_contact_handshake(project_key="/abs/path/to/repo", requester="GreenCastle",
- target="BlueLake", to_project="/abs/path/to/other/repo",
- auto_accept=true, welcome_subject="Coordination channel",
- welcome_body="Use thread FEAT-123 for the cutover")
- ```
- ---
- ## Agent Configuration
- The installer and `am` command auto-detect installed agents and write their configs in HTTP URL mode. The examples below are the manual fallback.
- ### Claude Code
- Add to your project's `.mcp.json` or `~/.claude/settings.json`:
- ```json
- {
- "mcpServers": {
- "agent-mail": {
- "command": "mcp-agent-mail",
- "args": []
- }
- }
- }
- ```
- Or for HTTP transport (when the server is already running):
- ```json
- {
- "mcpServers": {
- "agent-mail": {
- "type": "url",
- "url": "http://127.0.0.1:8765/mcp/"
- }
- }
- }
- ```
- ### Codex CLI
- The curl installer writes this automatically for detected Codex CLI installs. For source installs, manual setup, or custom endpoint overrides, add this to `~/.codex/config.toml`:
- ```toml
- [mcp_servers.mcp_agent_mail]
- url = "http://127.0.0.1:8765/mcp/"
- # Add this when HTTP bearer auth is enabled:
- http_headers = { Authorization = "Bearer <HTTP_BEARER_TOKEN>" }
- ```
- ### Gemini CLI
- Add to `~/.gemini/settings.json`:
- ```json
- {
- "mcpServers": {
- "agent-mail": {
- "command": "mcp-agent-mail",
- "args": []
- }
- }
- }
- ```
- For a project-local Gemini setup plus Agent Mail identity registration:
- ```bash
- scripts/register_gemini.sh /abs/path/to/repo
- AGENT_NAME=BlueLake AGENT_MODEL=gemini-2.5-pro scripts/register_gemini.sh /abs/path/to/repo
- ```
- ### Oh My Pi (OMP)
- `am setup run --agent omp` writes OMP's native project config at `.omp/mcp.json`
- and the active profile's user config. The default profile uses
- `~/.omp/agent/mcp.json`; named profiles selected through `OMP_PROFILE` (or the
- legacy `PI_PROFILE`) use `~/.omp/profiles/<name>/agent/mcp.json`. Profile names
- must use OMP's lowercase `[a-z0-9][a-z0-9._-]{0,63}` syntax; an invalid
- explicit profile fails closed instead of redirecting setup to the default.
- Setup also honors OMP's `PI_CONFIG_DIR` and default-profile `PI_CODING_AGENT_DIR`
- overrides, with a stricter path-safety contract: neither may contain `..`
- components. `PI_CONFIG_DIR` is rooted beneath the user's home directory;
- a relative `PI_CODING_AGENT_DIR` is resolved against the working directory,
- and an absolute path is accepted. For example, use `agent` instead of
- `foo/../agent`. Invalid overrides cause setup to fail before writing config
- files; setup also refuses symlink traversal when accessing those files.
- The project config is profile-independent and applies under every named OMP
- profile.
- `am setup run --agent omp --no-user-config` leaves active-user bytes untouched,
- but setup and status still read the authorities that decide whether the
- project entry can run. They check the active canonical `mcp.json`
- `disabledServers` list against all three accepted Agent Mail aliases
- (`mcp-agent-mail`, `mcp_agent_mail`, and `agent-mail`). OMP also discovers the
- read-only `.mcp.json` sibling after `mcp.json` in both project and active-user
- scopes. An exact repeated server name is shadowed by the earlier source, while a
- different Agent Mail alias remains a separate MCP key; setup status reports and
- fingerprints that conflict without mirror-writing the secondary file. Status
- also evaluates
- `mcp.enableProjectConfig` with OMP's persistent settings precedence: the active
- profile's `config.yml` (falling back to `config.yaml` only when it is absent).
- When both main YAML names are absent, an existing legacy `settings.json` or
- `agent.db` remains a migration authority and setup fails closed until OMP has
- migrated it or an operator has inspected it. Project settings providers then
- merge in runtime order: `.omp/settings.json`,
- `.omp/config.yml`, `.claude/settings.json`, `.codex/config.toml`,
- `.gemini/settings.json`, project-root `opencode.json` and `opencode.jsonc`,
- `.opencode/opencode.json` and `.opencode/opencode.jsonc`, and
- `.cursor/settings.json`. Ordered ambient `PI_CONFIG_FILES` overlays apply last.
- Foreign-provider parse failures are skipped as OMP skips them. Unsafe or
- unreadable paths still fail closed: OMP may follow a symlink or otherwise read
- bytes that Agent Mail deliberately refuses to trust, so treating that authority
- as absent could produce a false-green verdict. The active-profile YAML, native
- `.omp/config.yml`, and explicit overlays are also strict authorities. An
- effective `false`, an unsupported authority, or a missing explicit overlay is
- reported as runtime-relevant drift instead of success. OpenCode `{env:...}` and
- `{file:...}` substitutions are also reported
- unsupported because their external dependencies cannot be proven by a cache of
- the config bytes alone. Remediation deliberately omits `--no-user-config`,
- because a project-only write cannot overcome an authority that excludes every
- project MCP source.
- This check is bound to the persistent files and the `PI_CONFIG_FILES` value in
- the `am` process environment. A one-shot OMP `--config` argument or a
- programmatic runtime settings override is launch-specific and is outside this
- static setup/status boundary; run `am setup status` under the same ambient
- overlay environment used to launch OMP.
- To configure it manually:
- ```json
- {
- "mcpServers": {
- "mcp-agent-mail": {
- "type": "http",
- "url": "http://127.0.0.1:8765/mcp/"
- }
- }
- }
- ```
- When HTTP bearer authentication is enabled, add an `Authorization` entry under
- `headers`; `am setup run` does this automatically and adds `.omp/mcp.json` to
- the project `.gitignore` so the credential is not committed.
- ### Any MCP-Compatible Client
- Agent Mail supports both stdio and HTTP transports:
- - **stdio**: Run `mcp-agent-mail` as a subprocess (the default for most MCP clients)
- - **HTTP**: Connect to `http://127.0.0.1:8765/mcp/` when the server is running via `am` or `mcp-agent-mail serve`
- One server process owns a mailbox at a time. While `am` (or `mcp-agent-mail serve`) is serving a storage root, a stdio `mcp-agent-mail` started for the same root refuses to start ("another Agent Mail server is already serving this storage root") instead of contending for it, so configure clients with the HTTP URL whenever `am` runs; the installer and `am setup run` write HTTP URL entries.
- - **Examples**: Token-free client templates live under `docs/examples/mcp/`
- ---
- ## Server Modes
- ### MCP Server (default)
- ```bash
- mcp-agent-mail # stdio transport (for MCP client integration)
- mcp-agent-mail serve # HTTP server with TUI (default 127.0.0.1:8765)
- mcp-agent-mail serve --no-tui # Headless server (CI/daemon mode)
- mcp-agent-mail serve --reuse-running # Reuse existing server on same port
- ```
- ### CLI Operator Tool
- ```bash
- am # Start server + TUI (non-interactive: robot status)
- am serve-http --port 9000 # Different port
- am serve-http --setup # Explicitly update detected MCP clients before serving
- am serve-http --host 0.0.0.0 # Bind to all interfaces
- am serve-http --no-auth # Skip authentication (local dev)
- am serve-http --path api # Use /api/ transport instead of /mcp/
- am --help # Full operator CLI
- ```
- Server startup preserves existing MCP client configuration by default, including
- project and user-level URLs. Use `am setup run` to configure clients separately,
- or `am serve-http --setup` to update detected clients to that launch's endpoint.
- The setup flag can rewrite existing entries; omit it for temporary test servers.
- For CLI deployments that require an explicitly supplied sending credential, set
- `AGENT_MAIL_REQUIRE_EXPLICIT_SENDER_TOKEN=1`. `am mail send` then requires
- `--sender-token`, `--sender-token-file`, or `AGENT_MAIL_SENDER_TOKEN`; it refuses
- to borrow a token from persisted agent identity state. The same resolver applies
- to queued-send replay and contact handshakes (use the environment variable where
- the command has no token flag). The default retains automatic token reuse.
- This controls CLI token selection; it does not establish MCP session ownership
- or isolate hostile processes sharing the same OS account. Server-side verified
- send enforcement remains `MESSAGING_FAIL_CLOSED_SEND_PROFILE=true`.
- #### Session-bound agent identity (opt-in)
- Available since v0.3.39 (see [CHANGELOG.md](CHANGELOG.md)).
- Set `MESSAGING_SESSION_IDENTITY=true` on the server to let an MCP session act as
- the identities it established without a registration token in the model-visible
- transcript:
- - **The session.** Over stdio, the session is the client's server process. Over
- Streamable HTTP, a successful `initialize` returns an `Mcp-Session-Id` header;
- requests that send it back (over any connection) share the session, and
- `DELETE` on the MCP endpoint with the header ends it. A session is tied to the
- `Authorization` it was created under: another credential, an unknown id or an
- expired id (24 h idle) gets a stateless request. Sessions live in memory, so a
- restart ends them. Bearer/JWT authorization is still checked on every request:
- this is identity context inside an authorized connection, not authentication.
- - **Binding.** `create_agent_identity` (use `return_registration_token: false`
- to keep the token out of the transcript) binds the new agent, and so does a
- `register_agent` that creates its agent. Naming an existing agent never binds
- it.
- - **Acting as a bound agent.** `send_message` / `reply_message` from the session
- as a bound agent are verified without `sender_token` (`"verified_sender": true,
- "sender_verification": "session"`), including under
- `MESSAGING_FAIL_CLOSED_SEND_PROFILE`.
- - **No borrowed names.** A session that holds an identity in a project cannot,
- in that project, send/reply, read an inbox (`fetch_inbox`,
- `fetch_inbox_events`, or that project's view in `fetch_inbox_product`), mark
- read or acknowledge, reserve/renew/release files, manage build slots, request
- a forced reservation release, or re-register (rewriting the profile and
- rotating the token) as any other
- agent: those calls fail with `SESSION_IDENTITY_MISMATCH` (a send or reply that
- carries the other agent's own `sender_token` is still accepted). A session
- holding no identity in the project keeps the trusted-local behavior.
- - **Database outages.** ACKs and reservation releases can be queued durably
- after the acting identity is authorized. If an outage prevents that check
- and the session holds a potentially relevant binding, the call returns the
- database error without queuing an intent, even for its own supplied name.
- Retry after database access recovers. Already authorized intents remain
- replayable when another session triggers recovery.
- - **Lifecycle.** `retire_agent` / `deregister_agent` drop the identity from the
- calling session; lifecycle authorization itself is unchanged (registration
- token, or a bound tmux pane over stdio).
- This does not authenticate the model, provider or OS process, and it cannot
- isolate hostile clients that share one bearer credential and can read each
- other's session ids.
- When an interactive `am` finds a healthy Agent Mail service already serving the
- configured endpoint, it defaults to an attach/takeover/quit prompt
- (`AM_ATTACH_MODE=ask`). Enter chooses a read-only view of the service's
- `/mail/ws-state` snapshot; that attachment does not stop or restart the service,
- acquire a mutation lock, or run service-control commands. Set
- `AM_ATTACH_MODE=attach` to select it without prompting. Choose takeover, pass
- `--takeover`, or set `AM_ATTACH_MODE=takeover` for an explicit local replacement
- through the supervised service-control path; a managed service is restored when
- the local session ends. If this decision runs without interactive stdin, the
- default is read-only attachment.
- ### Dual-Mode Interface
- This project keeps MCP server and CLI command surfaces separate:
- | Use case | Entry point | Notes |
- |---------|-------------|-------|
- | MCP server (default) | `mcp-agent-mail` | Default: MCP stdio transport. HTTP: `serve`. |
- | CLI (operator + agent-first) | `am` | Recommended CLI entry point. |
- | CLI via single binary | `AM_INTERFACE_MODE=cli mcp-agent-mail` | Same CLI surface, one binary. |
- Running CLI-only commands via the MCP binary produces a deterministic denial on stderr with exit code `2`, and vice versa, preventing accidental mode confusion in automated workflows.
- ---
- ## Operator CLI Surface
- `am` is more than a launcher. It is the operator surface for runtime control, diagnostics, migration, exports, benchmarking, and agent-facing non-interactive workflows. In non-interactive contexts, bare `am` automatically falls back to robot output instead of trying to launch a blocking TUI.
- ### Command Families
- | Surface | Subcommands / form | What it is for |
- |---------|--------------------|----------------|
- | Runtime | `serve-http`, `serve-stdio`, `service install|status|logs|restart`, `check-inbox`, `inbox-events` | Start the server, run stdio MCP, manage a background service, poll inbox state, or resume a durable inbox monitor |
- | Quality gates | `ci`, `verify`, `lint`, `typecheck`, `bench` | Run the native quality pipeline, build-slot-protected verification lanes, and CLI/perf baselines |
- | E2E and determinism | `e2e list|run|show`, `golden capture|verify|list`, `flake-triage scan|reproduce|detect` | Test transports and workflows, guard CLI output contracts, and triage flaky failures |
- | Share and deploy | `share export|update|preview|verify|decrypt|wizard|static-export`, `share deploy validate|tooling|verify|verify-live` | Build portable mailbox bundles, preview them, and validate live static deployments |
- | Archive and recovery | `archive save|list|restore`, `doctor ...` (28 verbs: `check`, `health`, `triage`, `locks`, `drain`, `fix`, `undo`, `repair`, `reconstruct`, ...; see Family Detail) | Snapshot mailbox state, scan/archive hygiene, normalize safe archive debt, or repair/rebuild SQLite from the Git archive |
- | Coordination data | `agents ...`, `mail ...`, `contacts ...`, `macros ...`, `file_reservations ...`, `acks ...`, `list-acks` | Operate directly on the same concepts the MCP tools expose |
- | Project and product routing | `projects ...`, `products ...`, `list-projects`, `beads ...` | Manage project identity, cross-project product groupings, and task-tracker views |
- | Platform and setup | `setup run|status`, `config set-port|show-port`, `amctl env`, `tooling ...`, `docs insert-blurbs` | Bootstrap connectors, inspect runtime config, introspect tool schemas/metrics/locks, and stamp docs |
- | Migration and lifecycle | `legacy detect|import|status`, `upgrade`, `migrate`, `self-update`, `am-run`, `guard ...` | Migrate Python installs, perform DB-format upgrades, run slot-aware build commands, and manage guard hooks |
- | Break-glass admin | `clear-and-reset-everything` | Fully reset local state after optional archival. A running server holding the mailbox is stopped for the wipe: a systemd user service or LaunchAgent through its manager (and started again afterwards), any other Agent Mail process with SIGTERM, then SIGKILL after a grace period. Use sparingly. |
- ### Setup Drift Reports
- `am setup status` is read-only. It inventories supported MCP clients, reports the
- current redacted server entry beside the expected entry, and labels drift such
- as `missing_file`, `legacy_stdio`, `stale_http_path`, `wrong_bearer_header`,
- `wrong_startup_timeout`, `duplicate_server_entries`, and `unsupported_config`.
- Use the reported remediation in two steps:
- ```bash
- am setup status --format json
- am setup run --dry-run --project-dir "$PWD" --format toon
- am setup run --yes --project-dir "$PWD" --format toon
- ```
- For bearer-header checks, pass `--token` to `am setup status` or expose the
- expected token through `HTTP_BEARER_TOKEN` / `config.env`; status output redacts
- token values.
- ### Family Detail
- | Family | Current subcommands / modes |
- |--------|------------------------------|
- | `share` | `export`, `update`, `preview`, `verify`, `decrypt`, `wizard`, `static-export`, `deploy validate`, `deploy tooling`, `deploy verify`, `deploy verify-live` |
- | `archive` | `save`, `list`, `restore` |
- | `guard` | `install`, `uninstall`, `status`, `check` |
- | `file_reservations` | `list`, `active`, `soon`, `reserve`, `renew`, `release`, `conflicts` |
- | `acks` | `pending`, `remind`, `overdue` |
- | `projects` | `mark-identity`, `discovery-init`, `adopt` |
- | `mail` | `status`, `send`, `reply`, `inbox`, `read`, `ack`, `search`, `summarize-thread`, `replay-queued`, `discard-queued` |
- | `products` | `ensure`, `link`, `status`, `search`, `inbox`, `summarize-thread` |
- | `doctor` (28 verbs) | `check`, `health`, `triage`, `locks`, `drain`, `fix`, `undo`, `ls`, `explain`, `fixers`, `capabilities`, `robot-docs`, `artifacts`, `reclaim`, `selftest`, `mcp-selftest`, `write-selftest`, `support-bundle`, `repair`, `reconstruct`, `backups`, `restore`, `archive-scan`, `archive-verify`, `archive-normalize`, `fix-orphan-refs`, `pack-archive`, `vacuum` |
- | `agents` | `register`, `create`, `list`, `show`, `detect`, `reap`, `resolve-pane` |
- | `tooling` | `directory`, `schemas`, `metrics`, `metrics-core`, `diagnostics`, `locks`, `decommission-fts` |
- | `macros` | `start-session`, `prepare-thread`, `file-reservation-cycle`, `contact-handshake` |
- | `contacts` | `request`, `respond`, `list`, `policy` |
- | `beads` | `ready`, `list`, `show`, `status` |
- | `setup` | `run`, `status` |
- | `golden` | `capture`, `verify`, `list` |
- | `flake-triage` | `scan`, `reproduce`, `detect` |
- | `robot` | `status`, `inbox`, `timeline`, `overview`, `thread`, `search`, `message`, `navigate`, `reservations`, `metrics`, `health`, `analytics`, `agents`, `contacts`, `projects`, `attachments`, `atc`, `handoff`, `tui-dump` |
- | `verify` | `cargo-fmt`, `cargo-check`, `cargo-clippy`, `cargo-test`, `e2e-list`, `e2e-stdio`, `bench-quick`, `reliability-coverage` |
- | `legacy` | `detect`, `import`, `status` |
- | `service` | `install`, `uninstall`, `status`, `logs`, `restart` |
- ### Durable Inbox Event Cursors
- `am inbox-events` is the CLI for restart-safe inbox monitors. It reads
- append-only, body-free delivery events oldest first; its `--after` value is a
- delivery cursor, never a message ID. Persist `next_cursor` only after the
- corresponding events have been processed.
- ```bash
- # Establish a durable starting position without consuming events.
- am inbox-events --project /abs/path --agent BlueLake --position-now --format json
- # Resume from the last processed delivery cursor.
- am inbox-events --project /abs/path --agent BlueLake --after 42 --limit 100 --format json
- ```
- Each page includes `events`, `next_cursor`, `has_more`,
- `oldest_available_cursor`, and `tail_cursor`. Retention records durable loss
- markers for the affected recipient. Deleting another recipient's mail does
- not expire your cursor, and deleting the newest or every retained event does
- not move your durable tail backwards.
- If retention removed a delivery after your saved position, the read fails
- with code `cursor_expired` (the `fetch_inbox_events` tool reports
- `CURSOR_EXPIRED`). This also detects holes inside retained history, even when
- older events remain. The error's `oldest_available_cursor` identifies the first
- position after the lost history; after handling the loss according to your
- recovery policy, resume with `--after` set to that value minus one. The page's
- `oldest_available_cursor` still describes its oldest retained event. To
- intentionally start monitoring only future mail, use `--position-now`.
- A cursor beyond the durable tail fails with `cursor_ahead` (`CURSOR_AHEAD`);
- check that the cursor belongs to this mailbox and recipient before choosing a
- new position. The migration preserves the database's existing issued-cursor
- ceiling, including when all events were already deleted. It cannot reconstruct
- which recipients lost events before durable retention markers were introduced.
- ---
- ## The 45 MCP Tools
- ### 9 Clusters
- | Cluster | Count | Tools |
- |---------|-------|-------|
- | Infrastructure | 4 | `health_check`, `ensure_project`, `install_precommit_guard`, `uninstall_precommit_guard` |
- | Identity | 9 | `register_agent`, `create_agent_identity`, `retire_agent`, `unretire_agent`, `deregister_agent`, `whois`, `resolve_pane_identity`, `cleanup_pane_identities`, `list_agents` |
- | Messaging | 9 | `send_message`, `reply_message`, `fetch_inbox`, `fetch_topic`, `fetch_inbox_events`, `get_message_delivery_receipt`, `acknowledge_message`, `mark_message_read`, `mark_all_read` |
- | Contacts | 4 | `request_contact`, `respond_contact`, `list_contacts`, `set_contact_policy` |
- | File Reservations | 5 | `check_file_reservation_conflicts`, `file_reservation_paths`, `renew_file_reservations`, `release_file_reservations`, `force_release_file_reservation` |
- | Search | 2 | `search_messages`, `summarize_thread` |
- | Macros | 4 | `macro_start_session`, `macro_prepare_thread`, `macro_contact_handshake`, `macro_file_reservation_cycle` |
- | Product Bus | 5 | `ensure_product`, `products_link`, `search_messages_product`, `fetch_inbox_product`, `summarize_thread_product` |
- | Build Slots | 3 | `acquire_build_slot`, `renew_build_slot`, `release_build_slot` |
- `fetch_inbox_events` is the MCP equivalent of `am inbox-events`: it is a
- durable, recipient-scoped delivery feed for monitors, not a replacement for
- message-body inbox reads.
- `file_reservation_paths` accepts an optional `idempotency_key` for an exact
- retry after a timeout. The same key and normalized request replay the original
- grant without a second lease or archive write and mark the response
- `idempotent_replay: true`. Reusing a key with different arguments returns
- `IDEMPOTENCY_KEY_CONFLICT`. Keys are scoped to `(project, tool)`, expire after
- the configured retention window, and are optional; this is not a blanket
- idempotency claim for every mutating tool.
- On replay, `granted` contains the original IDs and expiries, even after release
- or expiry; it does not reacquire those paths. `conflicts` is a current snapshot.
- A partial or empty original grant stays partial or empty; use a new key for a
- new acquisition attempt. Fresh reacquisition of an active lease reuses its ID
- and applies the requested exclusive/shared mode and reason after checking peers.
- Keys recorded before the normalized path-set fingerprint update can return
- `IDEMPOTENCY_KEY_CONFLICT` after an upgrade, even within their retention window.
- The original grants remain unchanged; inspect them before making a new attempt.
- ### Agent identities
- Omit `name` from `register_agent` (or `name_hint` from `create_agent_identity`)
- to get an automatically generated adjective+noun name such as `GreenLake`.
- For a stable task identity, supply a name such as `app-x-refactor`, `worker_42`,
- or `api.review`.
- Explicit task identifiers start with an ASCII letter or digit, contain at
- least one `.`, `_`, or `-`, and use only ASCII letters, digits, and those
- separators, up to 128 characters. They preserve their spelling. Vocabulary
- names still normalize to PascalCase. Both forms are unique within a project
- without regard to case: registering `APP-X-REFACTOR` after `app-x-refactor`
- updates the same identity and returns its original canonical spelling.
- `create_agent_identity` instead rejects a name that is already in use.
- Path separators, address delimiters, consecutive or trailing dots, template
- placeholders, Windows device names, and reserved program/model/operator
- identities are rejected. Broadcast tokens remain unsupported. A dot inside
- an identity is part of its name; cross-project recipients still use
- `Name@project` or `project:project#Name` and require the usual contact approval.
- ### 25 MCP Resources
- Read-only resources span environment/config inspection, project and agent discovery, inbox and thread views, reservation views, and tooling diagnostics. They are there so agents can fetch state cheaply without mutating anything.
- ```
- resource://inbox/{Agent}?project=<abs-path>&limit=20
- resource://thread/{id}?project=<abs-path>&include_bodies=true
- resource://mailbox/{Agent}?project=<abs-path>
- resource://views/ack-overdue/{Agent}?project=<abs-path>
- resource://agents/<project-slug>
- resource://file_reservations/<project-slug>?active_only=true
- resource://tooling/metrics
- resource://config/environment
- ```
- `resource://agents/...` and `resource://file_reservations/...` take the project in the path segment. Inbox, mailbox, thread, and message resources put the agent or thread in the path and the project in the query string.
- ### Macros vs. Granular Tools
- - **Prefer macros when you want speed** or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`
- - **Use granular tools when you need control:** `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`
- ---
- ## TUI Operations Console
- The interactive TUI has 16 screens. Jump directly with `1`-`9`, `0` (screen 10), and shifted digits `!`, `@`, `#`, `$`, `%`, `^` (screens 11-16). Use `Tab`/`Shift+Tab` to cycle in order.
- | # | Screen | Shows |
- |---|--------|-------|
- | 1 | Dashboard | Real-time operational overview with event stream and anomaly rail |
- | 2 | Messages | Message browser with detail pane, presets, and compose/reply flows |
- | 3 | Threads | Thread explorer and conversation drill-down |
- | 4 | Agents | Agent roster with activity, state, and quick actions |
- | 5 | Search | Unified multi-scope search with facets and preview |
- | 6 | Reservations | File reservation status, conflicts, and create/release actions |
- | 7 | Tool Metrics | Per-tool call counts, latency distributions, and failures |
- | 8 | System Health | Probe/circuit/disk/memory diagnostics plus ATC health widget |
- | 9 | Timeline | Events/Commits/Combined/Log timeline views with inspector |
- | 10 | Projects | Project inventory and routing helpers |
- | 11 | Contacts | Contact links, policy view, and graph/mermaid modes |
- | 12 | Explorer | Unified inbox/outbox explorer with direction and ack filters |
- | 13 | Analytics | Anomaly insight feed with confidence and deep links |
- | 14 | Attachments | Attachment inventory with preview and provenance |
- | 15 | Archive Browser | Two-pane Git archive browser with tree + file preview |
- | 16 | ATC | Snapshot-driven ATC control surface with decision drill-in and retention report |
- **Global keys:** `?` help, `Ctrl+P`/`:` command palette, `/` the screen's own filter (global search focus on screens without one), `.` contextual action menu, `Ctrl+N` compose overlay, `Ctrl+Y` toast-focus mode, `Ctrl+T`/`Shift+T` cycle theme, `m` toggle MCP/API transport, `q` quit.
- **ATC keys:** `d` decision detail, `r` retention report, `i` toggle detail pane, `Tab` switch agents/decisions.
- **Screen-specific highlights:** Messages uses `g` for Local/Global inbox; Threads uses `e/c` for expand/collapse-all in conversation view; Timeline uses `V` for Events/Commits/Combined/Log and `v` for visual selection; Search uses `f` + facet rail navigation for scope/sort/field controls; Contacts uses `n` to cycle Table/Graph/Matrix (sender × recipient heatmap); batch-capable screens share `Space`/`v`/`A`/`C`; preset-enabled screens use `Ctrl+S`/`Ctrl+L`.
- **Compose from any screen:** Press `Ctrl+N`, choose the project with the arrow
- keys, then use `Tab` to reach recipients and the remaining fields. Existing
- active agents are loaded from that project's live mailbox. A mailbox with more
- than one project requires an explicit choice. Select recipients with `Space`
- and cycle their To/Cc/Bcc role with `Ctrl+T`; the Acknowledgement field can
- request a receipt. `Ctrl+R` refreshes projects and recipients, and
- `Ctrl+Enter` sends.
- Loading and delivery run in the background. A failed send keeps the draft;
- retrying it unchanged reuses its delivery key to avoid duplicate mail. While
- sending, the form prevents edits and duplicate submissions. `Esc` dismisses a
- pending form while delivery continues. Changing project clears its recipients
- and thread, preserving the message text; refreshing the same project keeps
- selected unavailable recipients visible until you explicitly remove them.
- **Command palette:** Press `Ctrl+P` (or `:` outside text-entry) to open a searchable action launcher that includes screen navigation, transport/layout controls, and dynamic entities (agents/projects/threads/tools/reservations).
- **Themes:** 42 named palettes are in the `Ctrl+T`/`Shift+T` cycle (Cyberpunk Aurora, Darcula, Lumen Light, Nordic Frost, High Contrast, Dracula, Monokai, Nord, and more; see `NAMED_THEMES` in `crates/mcp-agent-mail-server/src/tui_theme.rs`). The five config-level themes are selectable through `TUI_THEME`. Accessibility support includes high-contrast mode and reduced motion.
- Archive Browser note: use `Enter` to expand/preview, `Tab` to switch tree vs preview pane, `/` to filter filenames, and `Ctrl+D/U` for preview paging.
- If an interactive `am` attaches to an already running service, this terminal is
- read-only and detaches with `Ctrl-C`; the service keeps serving MCP/API traffic.
- Use an explicit `--takeover` only when replacement is intended.
- ---
- ## Robot Mode (`am robot`)
- Non-interactive, agent-first CLI surface for TUI-equivalent situational awareness. Use it when you need structured snapshots quickly, especially in automated loops and when tokens matter.
- ### 19 Subcommands
- | Command | Purpose | Key flags |
- |---------|---------|-----------|
- | `am robot status` | Dashboard synthesis | `--format`, `--project`, `--agent` |
- | `am robot inbox` | Actionable inbox with urgency/ack synthesis | `--urgent`, `--ack-overdue`, `--unread`, `--all`, `--limit`, `--include-bodies` |
- | `am robot timeline` | Project event stream (last 24h unless `--since`) | `--since`, `--kind`, `--source` |
- | `am robot overview` | Cross-project summary | `--format`, `--counts` |
- | `am robot thread <id>` | Full thread rendering | `--limit`, `--since`, `--format`, `--server` |
- | `am robot search <query>` | Full-text search with facets/relevance | `--kind`, `--importance`, `--since`, `--limit`, `--cursor`, `--format` |
- | `am robot message <id>` | Single-message deep view | `--format`, `--project`, `--server` |
- | `am robot navigate <resource://...>` | Resolve resources into robot-formatted output | `--format`, `--project`, `--agent` |
- | `am robot reservations` | Reservation view with conflict/expiry awareness; JSON entries carry absolute `granted_ts`/`expires_ts` (RFC 3339 UTC) and integer `remaining_seconds`/`granted_age_seconds` next to the humanized `remaining` | `--all`, `--conflicts`, `--expiring`, `--agent` |
- | `am robot metrics` | Tool call rates, failures, latency percentiles (server-wide) | `--format` |
- | `am robot health` | Runtime/system diagnostics (server-wide) | `--format`, `--include-host` |
- | `am robot analytics` | Anomaly and remediation summary | `--format`, `--project`, `--agent` |
- | `am robot agents` | Agent roster and activity overview | `--active`, `--sort` |
- | `am robot contacts` | Contact graph (incoming cross-project requests included) and policy surface | `--format`, `--project`, `--agent` (links on either side) |
- | `am robot projects` | Per-project aggregate stats (every project) | `--format` |
- | `am robot attachments` | Attachment inventory | `--format`, `--project` |
- | `am robot atc` | Live ATC snapshot with local DB fallback when the server is unavailable | `--since`, `--stratum`, `--summary-only`, `--limit` |
- | `am robot handoff` | Read-only stale bead ownership and handoff dashboard | `--stale-minutes`, `--active-minutes`, `--fresh-comment-minutes`, `--include-fresh`, `--dry-run` |
- | `am robot tui-dump` | TUI freeze escape hatch (alias of `am tui-dump`): the situational snapshot the TUI renders, fetched live or from local SQLite | `--format` |
- ### Output Formats
- - **`toon`** (default at TTY): Token-efficient, compact, optimized for agent parsing
- - **`json`** (default when piped): Machine-readable envelope with `_meta`, `_alerts`, `_actions`
- - **`md`** (`thread` and `message` only, and their default even when piped): Human-readable narrative for deep context. Pass `--format json` to pipe them into `jq`.
- ### Search Pages
- `am robot search` accepts `--limit` from 1 through 1000 (default 20) and
- `--cursor` to continue from the response's `next_cursor`:
- ```bash
- am robot search 'migration' --project /abs/path --limit 50 --format json
- am robot search 'migration' --project /abs/path --limit 50 --cursor '<next_cursor>' --format json
- ```
- Keep the query, project, and filters the same when resuming. Stop when
- `next_cursor` is absent. Both the existing live-server route and the local
- snapshot route carry the requested page size and cursor. Recipient-kind
- filtering (`--kind to`, `cc`, or `bcc`) resumes after the last displayed match,
- including when more matches remain inside a fetched backend page. Invalid
- limits and malformed cursors fail before opening a mailbox. Search pages
- reflect the current index; they do not freeze a changing corpus across calls.
- `am robot overview` summarizes the whole mailbox; the global `--project` and
- `--agent` flags do not scope this command. Message counts use one grouped query,
- and active reservations use one candidate scan with release-ledger filtering.
- `--counts` returns totals from the same aggregation. The snapshot cache is
- process-local, so separate CLI invocations each read the database.
- `am robot atc` reads the live ATC snapshot over `/mail/ws-state` when the local server is running and falls back to a local SQLite rollup/liveness view when that snapshot is unavailable. Use `--since` to trim recent decisions/executions, `--stratum` to focus open-stratum counts, and `--summary-only` for the compact health view.
- `am robot handoff` correlates in-progress beads with Agent Mail activity, active file reservations, thread mail, and recent comments. It is always read-only: reopen/takeover rows contain proposed `br update ... --status open --json` commands, but agents must inspect reservations, peer dirty work, and the related thread before running them.
- ### Agent Workflow Recipes
- ```bash
- # Startup triage
- am robot status --project /abs/path --agent AgentName
- # Immediate urgency pass
- am robot inbox --project /abs/path --agent AgentName --urgent --format json
- # Incremental monitoring loop
- am robot timeline --project /abs/path --agent AgentName --since 2026-02-16T10:00:00Z
- # Deep thread drill-down
- am robot thread br-123 --project /abs/path --agent AgentName --format md
- # Reservation safety check before edits
- am robot reservations --project /abs/path --agent AgentName --conflicts --expiring 30
- # Heavy verification recommendation with build-slot admission and rch
- am robot status --project /abs/path --agent AgentName --format json \
- | jq '.recommendations[] | select(.category == "verification_lane")'
- ```
- ---
- ## File Reservations for Multi-Agent Editing
- Before editing, agents reserve file paths to avoid conflicts:
- ```
- file_reservation_paths(project_key, agent_name, paths=["src/**"], ttl_seconds=3600, exclusive=true)
- ```
- The pre-commit guard (`mcp-agent-mail-guard`) installs as a Git hook and blocks commits that touch files reserved by other agents. Reservations are advisory, TTL-based, and support glob patterns.
- New reservation artifacts are named
- `id-<reservation-id>-g<db-generation>.json` and carry the same generation in
- their JSON. This prevents a re-created SQLite database from overwriting an
- older generation's row-id artifact. Readers still recognize legacy
- `id-<reservation-id>.json` artifacts; parity reports stamped artifacts from a
- different live generation as foreign-generation debris rather than current
- reservation drift.
- The guard has narrow operational exemptions: `.beads/**` metadata is always
- exempt so shared task-state commits cannot be stranded, and an agent's own
- reservation does not conflict with its commit. Source files reserved by another
- agent remain protected. When no matching mailbox archive can be found (including
- a proven slug collision), the hook emits a warning and allows the commit rather
- than turning stale/missing mailbox state into a universal commit gate.
- The pre-push hook lists the paths a push touches with one streamed
- `git rev-list | git diff-tree --stdin` pipeline per pushed ref, so its cost no
- longer grows with a git process per commit. The scan is bounded by
- `AGENT_MAIL_GUARD_PUSH_MAX_COMMITS` (default 2000 commits per ref, newest
- first), `AGENT_MAIL_GUARD_PUSH_MAX_PATHS` (default 100000 path records per
- ref) and `AGENT_MAIL_GUARD_PUSH_TIMEOUT_SECS` (default 120 seconds for the
- whole push); `0` removes a bound. Reaching a bound truncates the scan: the
- paths already read are still checked, and if none of them conflicts while
- another agent holds an active lease, the hook fails closed (exit 2) naming what
- was skipped and which variable to raise, the same way every other unfinished
- inspection does. `AGENT_MAIL_GUARD_MODE=warn` turns that into a warning.
- Installing with `am guard install <project> <repo> --prepush` also installs a
- composed post-commit hook. It independently checks the exact committed snapshot
- against active reservations, including both rename endpoints and every merge
- parent. A complete check in block mode records a private, signed admission in
- the repository's Git metadata. A later editing lease can then protect the next
- editor's work without vetoing publication of that already admitted commit.
- The pre-commit guard still checks staged changes; publishing never modifies
- the index or working tree.
- Pre-push skips only individually admitted commit objects. It still checks
- unadmitted ancestors and commits created without a successful admission, using
- the same scan bounds. Commit timestamps, branch names, replacement refs and
- grafts do not establish admission. Receipts are bound to the canonical
- repository, project and archive authority and the generated guard policy;
- copying receipts to another repository or changing that authority cannot reuse
- them. A failed or incomplete post-commit check leaves the commit unadmitted
- and prints a warning, since Git cannot veto a commit from that hook.
- Explicit bypass, disabled enforcement and warn mode never record admission.
- Ambiguous or malformed reservation evidence cannot record it either. Existing
- user hooks remain composed and are restored when the guard is uninstalled.
- Reinstall with `--prepush` to enable admission in repositories with older hooks.
- Shallow repositories, and platforms without directory-relative no-follow file
- operations, retain the ordinary pre-push reservation check without admission.
- | Area | Reserve glob |
- |------|-------------|
- | Core types/config | `crates/mcp-agent-mail-core/src/**` |
- | SQLite layer | `crates/mcp-agent-mail-db/src/**` |
- | Git archive | `crates/mcp-agent-mail-storage/src/**` |
- | Tool implementations | `crates/mcp-agent-mail-tools/src/**` |
- | TUI | `crates/mcp-agent-mail-server/src/tui_*.rs` |
- | CLI/launcher | `crates/mcp-agent-mail-cli/src/**` |
- ### Message and Thread Context Through the Server
- Use `--server` when the running daemon can answer but a new local database
- connection cannot be admitted:
- ```bash
- am robot message 1234 --project /abs/path --server --format json
- am robot thread 1234 --project /abs/path --server --limit 200 --format md
- am thread TKT-123 --project /abs/path --server --since 2026-01-01T00:00:00Z
- ```
- These commands preserve the normal message/thread output, including sender
- program/model, acknowledgement counts, message neighbours, whole-thread
- participants, and the newest `--limit` messages in chronological order with
- their full-thread positions. `--since` filters the count and displayed window;
- the subject and participants still describe the whole conversation. They pin
- the configured endpoint and bearer token, verify stored project identity, and
- never open a local mailbox or fall back to an archive. Older servers without
- complete context support are rejected explicitly. As with other MCP resources,
- BCC identities are redacted and excluded from the participant list.
- MCP clients can request these envelopes using
- `resource://message/<id>?project=<slug>&context=true&format=json` or
- `resource://thread/<id>?project=<slug>&context=true&limit=200&include_bodies=true&format=json`.
- Thread context accepts `since_ts` as an ISO-8601 timestamp. The versioned
- envelope includes stored project identity, a capture time and `complete=true`.
- All context fields come from one read snapshot. The server refuses conversations
- with more than 10,000 messages or receipt rows, more than 1,000 displayed
- messages, or more than 4 MiB of context; it never silently truncates those
- bounds. Resources without `context=true` keep their existing response formats.
- ### Complete Reservation Reads Through the Server
- Ordinary `resource://file_reservations/<slug>` pages include optional activity
- hints. Filesystem and Git enrichment share a 100 ms cooperative time budget;
- Git history is also capped at 1,000 commits per page and diffs are restricted
- to the reserved paths. `last_git_activity_ts` reports a recent touch found
- within `FILE_RESERVATION_ACTIVITY_GRACE_SECONDS`, not an exhaustive historical
- last-touch lookup. It is null if no recent touch was established. When the
- scan is incomplete, `stale_reasons` includes `git_activity_unknown`
- and `stale` remains false. Cancelling or abandoning a read stops its worker
- at the next checkpoint; a single filesystem or libgit2 call cannot be
- interrupted. Bounded reads always use libgit2, independently of the legacy
- `AM_GIT_LS_FILES_SHELL` and `AM_GIT_RESERVATION_ACTIVITY_SHELL` escape hatches
- for the single-pattern force-release probe. Snapshot modes omit activity
- enrichment entirely.
- Use `--server` to read reservations through the configured authenticated MCP
- endpoint while the server owns the mailbox:
- ```bash
- am reservations --project /abs/path --all --json --server
- am file_reservations active /abs/path --server
- am file_reservations list /abs/path --all --server
- ```
- These reads now use a complete database snapshot and can return more than the
- resource's normal 250-row page. Project identity, holder identities, lease rows,
- and the active-lease cutoff come from the same read snapshot. Historical leases
- retain their holder names even when those agents have retired. Navigation still
- applies the requested ordering and page after obtaining the complete set.
- MCP clients can request the same envelope with
- `resource://file_reservations/<slug>?snapshot=true&active_only=true&format=json`.
- It includes `schema_version`, `complete`, `project`, `agents`, `captured_ts`,
- `active_only`, `count`, and `reservations`. Set `active_only=false` to include
- released and expired leases. Snapshot mode accepts no `limit` or `offset` and
- refuses results exceeding 10,000 reservations, 10,000 holder identities, or
- 4 MiB of JSON. For history reads (`active_only=false`), a CLI receiving this
- specific capacity refusal negotiates `snapshot_pages=true` with the same
- authenticated server. The server captures a larger bounded set once, then
- returns immutable pages of at most 250 rows and 4 MiB each. This supports
- `am file_reservations list <project> --all` beyond the single-response limits
- without opening another database connection in the CLI.
- Paged snapshots allow at most 100,000 reservations and holder identities and
- 64 MiB of serialized pages, including repeated identity metadata. All rows,
- holder names, release states, and ordering (`created_ts`, then `id`) come from
- one database read snapshot. Changes after capture appear only in a new read.
- Each page includes `consistency: "materialized_snapshot"`, `snapshot_token`,
- `captured_ts`, `total_count`, `offset`, `count`, and an explicit `next_offset`
- (null on the terminal page), alongside `project`, `agents`, `active_only`, and
- `reservations`. `captured_ts` marks capture start, not an exact historical query
- timestamp. Continue with the same URI plus `snapshot_token=<token>` and
- `offset=<next_offset>`; do not supply `snapshot` or `limit` in paged mode.
- Tokens expire 300 seconds after publication, do not survive server restart,
- and remain bound to the mailbox engine generation, project identity, and
- active/history scope. Every continuation requires normal server authentication.
- New pages advertise `supports_release: true`. Once a client finishes or abandons
- the read, it can free the snapshot using the same URI with its `snapshot_token`
- and `snapshot_release=true`, omitting `offset`. Release is authenticated, scoped,
- and idempotent; page retries remain valid until release or expiry. The CLI makes
- this best-effort cleanup request after success or a pagination failure, with a
- two-second request timeout. Cleanup failure does not replace the listing or its
- original error; expiry handles crashes, lost connectivity, and older paged servers
- that do not advertise release.
- The server retains at most four snapshots within a 128 MiB serialized cache
- budget; in-progress captures reserve capacity too. A full cache, expired token,
- oversized individual row/identity metadata, or exceeded aggregate bound is an
- explicit error. The CLI validates every page, permits at most 1,024 requests
- within a 300-second history-read budget, and displays nothing until the entire
- set and final project identity checks succeed. Retry a failed read from the
- beginning; partial results are never reported as complete.
- This path requires both the updated CLI and server. Older servers that return
- only ordinary arrays cannot provide the paged snapshot guarantee; the CLI
- retains the original size refusal and gives an upgrade/restart hint. Existing
- small legacy reads still require a short explicit page to prove completeness.
- Active-only safety reads retain the original single-snapshot limits. Ordinary
- resource reads without either snapshot mode keep independent `limit`/`offset`
- pagination and are not a consistent snapshot. Server rejection diagnostics
- retain the numeric error code and sanitized reason; only actual HTTP
- authentication failures receive authentication guidance.
- ---
- ## Multi-Agent Coordination Workflows
- ### How Agents Interact (Protocol Flow)
- ```mermaid
- sequenceDiagram
- participant A as Agent A (GreenCastle)
- participant S as Agent Mail Server
- participant B as Agent B (BlueLake)
- A->>S: ensure_project(human_key="/abs/path")
- A->>S: register_agent(project_key="/abs/path", program="claude-code")
- S-->>A: identity: GreenCastle
- B->>S: register_agent(project_key="/abs/path", program="codex-cli")
- S-->>B: identity: BlueLake
- A->>S: file_reservation_paths(project_key="/abs/path", agent_name="GreenCastle", paths=["src/auth/**"], exclusive=true)
- S-->>A: reserved ✓
- B->>S: file_reservation_paths(project_key="/abs/path", agent_name="BlueLake", paths=["src/auth/**"], exclusive=true)
- S-->>B: CONFLICT — reserved by GreenCastle
- B->>S: file_reservation_paths(project_key="/abs/path", agent_name="BlueLake", paths=["tests/api/**"], exclusive=true)
- S-->>B: reserved ✓
- A->>S: send_message(project_key="/abs/path", sender_name="GreenCastle", to=["BlueLake"], thread_id="FEAT-123", ack_required=true)
- S-->>B: new message in inbox
- B->>S: fetch_inbox(project_key="/abs/path", agent_name="BlueLake")
- S-->>B: [message from GreenCastle]
- B->>S: acknowledge_message(project_key="/abs/path", agent_name="BlueLake", message_id=1482)
- S-->>A: ack received ✓
- A->>S: release_file_reservations(project_key="/abs/path", agent_name="GreenCastle", paths=["src/auth/**"])
- S-->>A: released ✓
- ```
- ### Same Repository
- 1. **Register identity:** `ensure_project(human_key=<abs-path>)` + `register_agent(project_key=<abs-path>, ...)`
- 2. **Reserve files before editing:** `file_reservation_paths(project_key, agent_name, paths=["src/**"], ttl_seconds=3600, exclusive=true)`
- 3. **Communicate with threads:** `send_message(..., thread_id="FEAT-123")`, check with `fetch_inbox`, acknowledge with `acknowledge_message`
- 4. **Quick reads:** `resource://inbox/{Agent}?project=<abs-path>&limit=20`
- 5. **Tell the whole project once:** address the project's shared mailbox as `project:<slug>` (or `project:<human_key>`). Available since v0.3.39 (see [CHANGELOG.md](CHANGELOG.md)):
- ```
- send_message(project_key="/abs/path", sender_name="GreenCastle",
- to=["project:abs-path"], subject="Schema freeze until 18:00",
- body_md="Do not touch migrations/ until the release is cut.", ack_required=true)
- ```
- - The message is stored **once**, with one project delivery: no per-agent copies, rows, signals or archive inbox files. This is not `broadcast` (which stays rejected).
- - Every other non-retired agent of the project that was registered when the message was sent sees it in `fetch_inbox` (and `resource://inbox/...`, `am robot inbox`) with `"via": "project"`. An agent that joins later is not handed the backlog; project history stays readable through threads, `fetch_topic` and search. An agent whose `contact_policy` is `block_all` opts out, and a direct to/cc/bcc delivery to the same agent takes precedence so nothing appears twice.
- - Read and acknowledgement state is per agent and recorded lazily: `fetch_inbox` read receipts, `mark_message_read`, `acknowledge_message` and `mark_all_read` record only the calling agent's state. `get_message_delivery_receipt` reports the delivery under `project_mailbox` with each visible agent's read/ack state.
- - It can be combined with named recipients in `to`/`cc`, cannot be `bcc`, and can only name the sender's own project. Replies may address it too.
- - Retention treats a project message as settled only after every agent that can see it has read it (and acknowledged it when required). Archive reconstruction restores the delivery from the canonical message's `to`/`cc` envelope, and salvage restores the per-agent receipts.
- - Restart-safe monitors see it too: a project delivery appends one event to the durable `fetch_inbox_events` / `am inbox-events` cursor ledger, and each visible agent's page includes it (`"kind": "project"`) under the same single cursor.
- - `am robot overview` and `am robot overview --counts` include each visible agent's unread, urgent-unread, and overdue acknowledgement obligations. One shared message can therefore count for several agents, while a named recipient is counted only once; generating the overview never creates receipts or marks mail read.
- ### Across Different Repos
- - **Option A (single project bus):** Register both repos under the same `project_key`. Keep reservation patterns specific (`frontend/**` vs `backend/**`).
- - **Option B (separate projects):** Each repo has its own `project_key`. Link two agents with a contact handshake, then address the other agent with a project-qualified name:
- ```
- macro_contact_handshake(project_key="/abs/path/frontend", requester="BlueLake",
- target="GreenCastle", to_project="/abs/path/backend",
- auto_accept=true)
- send_message(project_key="/abs/path/frontend", sender_name="BlueLake",
- to=["GreenCastle@/abs/path/backend"], subject="API change",
- body_md="Please bump /v2.", thread_id="br-124", ack_required=true)
- ```
- - `Name@project` takes the project's human key or its slug (as returned by `ensure_project` and listed by `resource://projects`), and so does the older `project:<project>#Name` form. The qualified name is resolved in that project only and is never auto-registered.
- - The message is delivered only while an approved, unexpired contact link exists between the two agents (in either direction). Without one the send fails with `CONTACT_REQUIRED` and a ready `macro_contact_handshake` call; a blocked link or a `block_all` recipient fails with `CONTACT_BLOCKED`. This holds even when the recipient's own contact policy is `open`.
- - The message is stored in the recipient's project, so the recipient reads it with its ordinary `fetch_inbox`, acknowledges it with `acknowledge_message`, and answers with `reply_message` in its own project. A default reply to a message from another project goes back to the original sender in that sender's project over the same link.
- - One message lives in one project: a send may address agents of one other project, or local agents, but not both (`INVALID_ARGUMENT`; send twice instead).
- - A plain name still addresses only the sender's project. Naming a contact from another project, or an agent registered in another project of the same product, is refused with `CROSS_PROJECT_RECIPIENT` (the error carries the qualified address to use); no same-name placeholder is created.
- The product bus (`fetch_inbox_product`, `search_messages_product`, `summarize_thread_product`) aggregates an agent's inboxes and threads across the linked projects.
- ### External Git Coordination (opt-in)
- `mcp-agent-mail` serializes its own in-process git shell-outs via
- per-repo `flock` on `<repo>/.git/am.git-serialize.lock`. External tools
- (wrapper scripts, editor integrations, CI) can honor the same sentinel
- by invoking git through `scripts/git-with-amlock.sh`:
- ```bash
- # one-time: put the wrapper on PATH
- install -m755 scripts/git-with-amlock.sh ~/.local/bin/git-with-amlock
- # per-shell: resolve an "am-aware" git for automation
- export GIT_BIN="$(command -v git-with-amlock || command -v git)"
- alias gitam='"$GIT_BIN"'
- # your automation invokes gitam instead of git:
- gitam status
- gitam commit -m 'synced'
- ```
- **Scope of the mitigation:**
- - mcp-agent-mail's own in-process calls → always coordinated
- (automatic).
- - External tools that opt into the wrapper → coordinated.
- - Your IDE running `git commit` directly, with no wrapper →
- **still races**. The only complete mitigation for that case is to
- set `AM_GIT_BINARY` to a safe git binary, or upgrade/downgrade the
- system git. See the
- [Known-bad git versions](#known-bad-git-versions) section.
- The wrapper honors `AM_GIT_BINARY` for binary selection and
- `AM_GIT_FLOCK_TIMEOUT_SECS` (default 60s) for the bounded wait cap.
- Exit code 75 (`EX_TEMPFAIL`) signals a flock timeout.
- ### With Beads Task Tracking
- Agent Mail pairs with [Beads](https://github.com/Dicklesworthstone/beads_rust) (`br`) for dependency-aware task selection:
- 1. **Pick ready work:** `br ready --json` (choose highest priority, no blockers)
- 2. **Reserve edit surface:** `file_reservation_paths(..., reason="br-123")`
- 3. **Announce start:** `send_message(..., thread_id="br-123", subject="[br-123] Start: <title>", ack_required=true)`
- 4. **Work and update:** Reply in-thread with progress
- 5. **Complete and release:** `br close 123`, `release_file_reservations(...)`, final Mail reply
- Use the Beads issue ID (`br-123`) as the Mail `thread_id` and prefix message subjects with `[br-123]` to keep everything linked.
- ## Web UI
- The server includes a lightweight, server-rendered web UI for humans at `/mail/`. Agents should continue using MCP tools and resources; the web UI is for human review and oversight. Use `/mail/*` for mailbox and task oversight. The authenticated live browser TUI mirror at `/web-dashboard` remains deferred and is not a supported surface.
- The project website separately embeds the real production `DashboardScreen` through
- `crates/mcp-agent-mail-dashboard-wasm/` and FrankenTUI's browser renderer. That surface
- is an interactive, read-only public replay: six SQLite aggregate counts are real, while
- all names, paths, messages, and replay events are synthetic. It does not connect to a
- visitor's mailbox or expose the deferred `/mail/ws-input` path. The deterministic opening
- frame carries 192 synthetic history events, 500 agent rows, 41 project rows, and 200
- contact rows so the production dashboard opens at the same busy visual density as a real
- operator session without publishing mailbox content. See
- [`docs/SPEC-browser-parity-contract-deferred.md`](docs/SPEC-browser-parity-contract-deferred.md)
- for the shipped replay boundary and the still-deferred live parity contract.
- ### Routes
- | Route | What You See |
- |-------|-------------|
- | `/mail/` and `/mail/unified-inbox` | Unified inbox across all projects with importance filtering and related-project context |
- | `/mail/projects` | Project inventory page for browsing into one mailbox at a time |
- | `/mail/{project}` | Project overview with the six most recently active conversations, search, agent roster, and quick links |
- | `/mail/{project}/threads` | All project conversations, with subjects, canonical IDs, message counts, timestamps, and older/newer navigation |
- | `/mail/{project}/inbox/{agent}` | Reverse-chronological inbox for one agent with pagination and mark-read actions |
- | `/mail/{project}/message/{id}` | Full message detail with metadata, recipients, thread preview, and attachments |
- | `/mail/{project}/thread/{thread_id}` | Full thread rendering with chronological conversation context |
- | `/mail/{project}/thread?thread_id=...` | Query-form conversation link, including dot-only identifiers that browsers normalize in URL paths |
- | `/mail/{project}/search?q=...` | Search V3-powered query route with field filters (`subject:foo`, `body:"multi word"`) |
- | `/mail/{project}/file_reservations` | Active and historical file reservations |
- | `/mail/{project}/attachments` | Messages with attachments and provenance |
- | `/mail/{project}/overseer/compose` | Human compose form for pushing high-priority instructions to agents |
- | `/mail/api/unified-inbox` | JSON feed backing the unified inbox |
- | `/mail/api/projects/{project}/agents` | JSON roster for one project |
- | `/mail/archive/*` | Archive browser and time-travel routes |
- Auth: HTTP authentication is off when neither `HTTP_BEARER_TOKEN` nor JWT auth
- is configured; this supports the trusted-local deployment described in
- [`SECURITY.md`](SECURITY.md). Configure a bearer token or JWT before exposing the
- server beyond loopback. With auth configured,
- `HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED=true` explicitly permits the guarded local
- bypass; it is not needed for no-token operation. These transport controls do not
- isolate hostile clients sharing the same OS account or bearer credential.
- ### Browsing conversations
- Open **Threads** or **Browse all threads** from a project to browse its conversations
- without searching first. The browser defaults to 50 conversations per page;
- `?limit=...` accepts up to 200. Conversations are ordered by their latest message's
- timestamp and message ID. Older/newer links retain a message watermark, so new
- messages do not move conversations between pages during a browsing session. Use
- **Latest conversations** to refresh that view.
- Each nonblank explicit thread ID is preserved exactly. A message with no thread
- ID uses its decimal message ID as its conversation key, joining replies with that
- same key. Numeric keys never expand into an unrelated named conversation; `42`
- and `0042` stay distinct. Thread links in search, message details, and inboxes use
- the same identity rules and remain scoped to the message's project.
- The conversation list reads indexed message metadata and hydrates only the selected
- subjects. It does not load message bodies or change read/acknowledgement receipts.
- The dynamic browser is omitted from static-export project pages.
- ### Human Overseer
- Sometimes you need to redirect agents mid-session. The **Overseer** compose form at `/mail/{project}/overseer/compose` lets humans send high-priority messages directly to any combination of agents.
- Overseer messages:
- - Come from a special `HumanOverseer` agent (program: `WebUI`, model: `Human`)
- - Are always marked **high importance** so they stand out in agent inboxes
- - Bypass normal contact policies so you can always reach any agent
- - Include a preamble instructing agents to pause current work, handle the request, then resume
- Agents see overseer messages in their normal inbox via `fetch_inbox` or `resource://inbox/{name}?project=<abs-path>`. They can reply in-thread like any other message. The send writes the message to SQLite; the background DB-to-archive reconciler then writes its Git archive copy, in the same envelope as agent-to-agent mail, so it is auditable once reconciled.
- ---
- ## Deployment Validation
- ```bash
- # Export a bundle
- am share export -o /tmp/agent-mail-bundle --no-zip
- # Verify a live deployment against the bundle
- am share deploy verify-live https://example.github.io/agent-mail \
- --bundle /tmp/agent-mail-bundle \
- --json > /tmp/verify-live.json
- # Inspect verdict
- jq '.verdict, .summary, .config' /tmp/verify-live.json
- ```
- Exit codes: `0` = pass, `1` = fail.
- ---
- ## Configuration
- All configuration via environment variables. The server reads them at startup via `Config::from_env()`.
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `AM_INTERFACE_MODE` | (unset = MCP) | `mcp` or `cli` |
- | `HTTP_HOST` | `127.0.0.1` | Bind address |
- | `HTTP_PORT` | `8765` | Bind port |
- | `HTTP_PATH` | `/mcp/` | MCP base path |
- | `HTTP_BEARER_TOKEN` | (unset unless configured, including via `.env`) | HTTP bearer credential; with JWT auth also disabled, an unset token leaves HTTP authentication off for trusted-local operation |
- | `HTTP_ALLOWED_HOSTS` | (none) | Comma-separated extra `Host:` header values the HTTP listener accepts, in addition to the bind host, its loopback variant, and `localhost`. Set this (or pass repeatable `serve-http --allowed-host <HOST>`) to reach the `/mail` web UI via a hostname or reverse proxy instead of getting an HTTP 421. Empty by default (loopback-only). |
- | `DATABASE_URL` | `<STORAGE_ROOT>/storage.sqlite3` | SQLite connection URL. Unset, the database lives inside `STORAGE_ROOT`; an explicit relative path is resolved against the working directory |
- | `AM_CACHE_PROFILE` | `balanced` | Cache budget preset: `conservative`, `balanced`, or `high-memory` |
- | `DATABASE_CACHE_BUDGET_KB` | profile-derived `524288` | Total SQLite page-cache budget across pooled connections, clamped to 16 MiB..4 GiB |
- | `AM_READ_CACHE_ENTRIES_PER_CATEGORY` | profile-derived `16384` | Per-category read-cache entry cap, clamped to 1,024..1,048,576 |
- | `STORAGE_ROOT` | XDG-aware (see below) | Archive root directory |
- | `ALLOW_EPHEMERAL_PROJECTS_IN_DEFAULT_STORAGE` | `false` | Permit `/tmp`-style project roots in the default global mailbox archive. Prefer a per-run `STORAGE_ROOT` instead. |
- | `LOG_LEVEL` | `info` | Minimum level for Agent Mail's own logs: `trace`, `debug`, `info`, `warn`, `error` or `off` (`WARNING`/`CRITICAL` accepted). Dependencies log at `warn` unless `LOG_LEVEL` is stricter. `RUST_LOG`, when set, replaces it for `mcp-agent-mail` (and for `am` with `AM_ALLOW_DEBUG_STARTUP_LOGS=1`) |
- | `TUI_ENABLED` | `true` | Interactive TUI toggle |
- | `TUI_HIGH_CONTRAST` | `false` | Accessibility mode |
- | `AM_TUI_TOAST_ENABLED` | `true` | Enable toast notifications |
- | `AM_TUI_TOAST_SEVERITY` | `info` | Minimum toast severity (`info`/`warning`/`error`/`off`) |
- | `AM_TUI_TOAST_POSITION` | `top-right` | Toast stack position |
- | `AM_TUI_TOAST_MAX_VISIBLE` | `3` | Max visible toasts at once |
- | `AM_TUI_TOAST_INFO_DISMISS_SECS` | `5` | Info toast auto-dismiss timeout |
- | `AM_TUI_TOAST_WARN_DISMISS_SECS` | `8` | Warning toast auto-dismiss timeout |
- | `AM_TUI_TOAST_ERROR_DISMISS_SECS` | `15` | Error toast auto-dismiss timeout |
- | `AM_TUI_THREAD_PAGE_SIZE` | `20` | Thread conversation page size |
- | `AM_TUI_THREAD_GUIDES` | `rounded` (theme default) | Thread tree guide style (`ascii`/`unicode`/`bold`/`double`/`rounded`) |
- | `AM_TUI_COACH_HINTS_ENABLED` | `true` | Enable contextual coach-hint notifications |
- | `AM_TUI_EFFECTS` | `true` | Enable text/animation effects |
- | `AM_TUI_AMBIENT` | `subtle` | Ambient mode (`off`/`subtle`/`full`) |
- | `AM_TUI_FULL_REDRAW_MAX_SECS` | `30` | Wall-clock bound (seconds) for a guaranteed full TUI redraw that repairs terminal desync (e.g. after a mux pane swap). Each forced redraw resends the whole screen, so lower values cost terminal output; `<= 0` disables the bound |
- | `AM_IDEMPOTENCY_RETENTION_SECS` | `86400` | Retention window in seconds for `file_reservation_paths` idempotency keys; invalid or non-positive values fall back to 24 hours |
- | `WORKTREES_ENABLED` | `false` | Enables build slots and the product bus (`ensure_product`, `products_link`, `search_messages_product`, `fetch_inbox_product`, `summarize_thread_product`); while off, those tools return `FEATURE_DISABLED`. `GIT_IDENTITY_ENABLED=true` also enables them |
- | `INTEGRITY_CHECK_ON_STARTUP` | `true` | Run the boot-time `PRAGMA quick_check`; `false` skips only this probe and leaves the background guard enabled |
- | `INTEGRITY_GUARD_ENABLED` | `true` | Enable periodic integrity checks, automatic backups and database maintenance; `false` stops that worker |
- | `INTEGRITY_QUICK_CHECK_INTERVAL_SECONDS` | `300` | Background quick-check cadence and initial delay when startup checking is skipped (minimum 1 second) |
- | `INTEGRITY_CHECK_INTERVAL_HOURS` | `1` | Periodic full integrity-check cadence (`0` disables scheduled full checks; quick checks remain enabled) |
- | `STARTUP_READINESS_BIND_TIMEOUT_SECS` | `20` | Max seconds to wait for DB readiness before binding the listener anyway (`/healthz` stays up while the DB warms) |
- | `DB_MAINTENANCE_ENABLED` | `true` | Enable checkpoint/ANALYZE/VACUUM/journal-size maintenance within the integrity guard; `false` leaves checks and backups enabled |
- | `DB_CHECKPOINT_INTERVAL_SECS` | `300` | Passive WAL checkpoint cadence (`0` disables that op) |
- | `DB_ANALYZE_INTERVAL_SECS` | `21600` | `ANALYZE` planner-stats refresh cadence (`0` disables) |
- | `DB_VACUUM_INTERVAL_SECS` | `86400` | Isolated ATC telemetry sidecar `VACUUM` cadence (`0` disables). Main-mailbox compaction requires a stopped server and explicit `am doctor vacuum --yes`. |
- | `DB_JOURNAL_SIZE_LIMIT_BYTES` | `16777216` | `journal_size_limit` WAL truncation cap (16 MiB); an automatic checkpoint over the cap truncates the WAL |
- | `AM_GIT_BINARY` | (resolver) | Override the `git` binary for all in-process shell-outs (mitigates the git 2.51.0 index race) |
- | `AM_GIT_FLOCK_TIMEOUT_SECS` | `60` | Bounded wait for the per-repo `am.git-serialize.lock` before a git shell-out fails `EX_TEMPFAIL` (75) |
- | `AGENT_MAIL_GUARD_PUSH_MAX_COMMITS` | `2000` | Most commits the pre-push guard inspects per pushed ref (newest first); past it the scan is truncated and fails closed. `0` removes the bound |
- | `AGENT_MAIL_GUARD_PUSH_MAX_PATHS` | `100000` | Most `--name-status` path records the pre-push guard reads per pushed ref before truncating. `0` removes the bound |
- | `AGENT_MAIL_GUARD_PUSH_TIMEOUT_SECS` | `120` | Wall-clock budget for the whole pre-push path scan; git is killed at the deadline and the scan is truncated. `0` removes the bound |
- For the full list of 100+ env vars, see `crates/mcp-agent-mail-core/src/config.rs`.
- The feature-flag and tuning-knob registry is inspectable at runtime with
- `am flags list` (`--subsystem atc`, `--set` for non-defaults, `--json`) and
- `am flags explain <VAR>`; see [docs/FLAGS_REGISTRY.md](docs/FLAGS_REGISTRY.md).
- ### Air Traffic Control (ATC) configuration
- ATC is the built-in operator that reviews agent liveness, detects reservation
- deadlocks, and can send probe/advisory mail or reclaim reservations. It is **on
- by default**, but since v0.3.31 its executor defaults to `shadow`, so a fresh
- install observes and decides without writing any mail. The whole surface is
- the `AM_ATC_*` family below; `am config atc` (alias of `am flags list
- --subsystem atc`) prints each variable's effective value and whether it came
- from the process environment, the persisted config file, a project `.env`, or
- the compiled default. Restart the server after changing any of them except the
- two canary-report paths.
- | Variable | Default | Meaning |
- |----------|---------|---------|
- | `AM_ATC_ENABLED` | `true` | Master switch. `false` stops the operator loop and makes the engine ignore every hook: no probes, advisories, reservation releases, population hydration, or experience rows. Liveness surfaces then fall back to the database `last_active_ts` written by ordinary tool calls ("passive liveness only"), and reservations held by crashed agents are reclaimed only by TTL expiry. Also forced `false` by `ATC_LEARNING_DISABLED`. |
- | `AM_ATC_EXECUTOR_MODE` | `shadow` | How decisions become side effects: `shadow` (observe/decide, emit nothing durable), `dry_run` (same, suppressed effects shown in the operator snapshot), `canary` (send activity-check / acknowledgment-request mail, never force-release reservations), `live` (everything, including releases). Unknown values fall back to `shadow`. |
- | `AM_ATC_WRITE_MODE` | `off` | Experience-ledger persistence: `off`, `shadow` (trace-log only), `live` (append rows to the ATC sidecar). Durable rows additionally need `canary`/`live` executor mode and a file-backed DB. Forced `off` by `ATC_LEARNING_DISABLED`. |
- | `AM_ATC_PROBE_INTERVAL_SECS` | `120` | Operator tick interval and per-agent liveness-probe cadence (floor 5; ticks never run faster than 250 ms). |
- | `AM_ATC_ADVISORY_COOLDOWN_SECS` | `300` | Minimum seconds between advisories to the same agent (floor 10). |
- | `AM_ATC_SUMMARY_INTERVAL_SECS` | `300` | Seconds between ATC summary lines in the console/log (floor 10). |
- | `AM_ATC_SAFE_MODE_RECOVERY_COUNT` | `20` | Consecutive correct liveness predictions required to leave safe mode (floor 1). |
- | `AM_ATC_EPROCESS_THRESHOLD` | `20` | E-process calibration alert threshold; crossing it enters safe mode (`20` ≈ 5% significance). Finite, `> 0`. |
- | `AM_ATC_CUSUM_THRESHOLD` | `5` | CUSUM change-point threshold on prediction error. Finite, `> 0`. |
- | `AM_ATC_CUSUM_DELTA` | `0.1` | Minimum shift the CUSUM detector is tuned to catch. Finite, `> 0`. |
- | `AM_ATC_LEDGER_CAPACITY` | `1000` | In-memory evidence-ledger ring buffer size (entries) behind transparency cards (floor 10). |
- | `AM_ATC_SUSPICION_K` | `3` | Rhythm-based liveness factor: an agent is suspect once its silence exceeds its expected gap by `k` standard deviations; lower probes sooner. Finite, `> 0`. |
- | `AM_ATC_EXPERIENCE_MAX_ROWS` | `50000` | Ceiling on raw `atc_experiences` rows in the sidecar; the retention sweep rolls up/evicts above it. `0` disables. |
- | `AM_ATC_RETENTION_SWEEP_INTERVAL_SECS` | `900` | Cadence of the sweep enforcing the ceiling above. `0` disables the sweep. |
- | `AM_ATC_POPULATION_RECENCY_SECS` | `604800` | Only agents active within this window (7 days) are hydrated into ATC on cold start / periodic sync. Lower it on mailboxes with many recently-active identities to bound cold-start effect bursts. `0` hydrates nobody. |
- | `AM_ATC_POPULATION_LIMIT` | `4096` | Maximum agents materialized per population sync, most recently active first (clamped to `1..=65536`). |
- | `AM_ATC_POLICY_BUNDLE_PATH` | `(unset)` | Path to a liveness policy bundle JSON to load instead of the compiled-in baseline. |
- | `AM_ATC_CANARY_REPORT_PATH` | `(unset)` | Exact canary perf-gate report JSON for `am robot atc` / the TUI; default `<STORAGE_ROOT>/atc_perf_gate/latest_canary_report.json`. Read per render. |
- | `AM_ATC_CANARY_REPORT_DIR` | `(unset)` | Directory holding `latest_canary_report.json`; `AM_ATC_CANARY_REPORT_PATH` wins if both are set. Read per render. |
- | `ATC_LEARNING_DISABLED` | `false` | Hard kill switch (no `AM_` prefix, kept for compatibility): forces `AM_ATC_ENABLED=false` and `AM_ATC_WRITE_MODE=off` regardless of the values above. Dynamic: `am flags on ATC_LEARNING_DISABLED`. |
- The file `<STORAGE_ROOT>/.atc_kill_switch` additionally stops durable ATC writes
- without a restart (checked every operator tick).
- To keep ATC's observation but stop it from writing mail, leave the default
- `AM_ATC_EXECUTOR_MODE=shadow`; to switch ATC off entirely use
- `AM_ATC_ENABLED=false`.
- For operations guidance and troubleshooting, see
- [docs/OPERATOR_RUNBOOK.md](docs/OPERATOR_RUNBOOK.md). For copy-paste operator
- recipes, see [docs/OPERATOR_COOKBOOK.md](docs/OPERATOR_COOKBOOK.md).
- ### Registration Proof Gate (optional, off by default)
- By default Agent Mail uses a **self-asserted** identity model: any caller may
- `register_agent` under any well-formed name. That is the right trade-off for
- local, trusted, single-operator multi-agent coordination and remains the
- default — nothing changes unless you opt in.
- Deployments where agents come from **different operators or less-trusted
- sources** can require a cryptographic proof before any identity is persisted.
- When enabled, `register_agent` (and every other path that can implicitly
- create an agent row, including `send_message` / `request_contact`
- auto-registration and the CLI) demands a `registration_proof` argument: a JSON
- bundle binding the final agent name, project key, program, model, capability
- scope, an `issued_at`/`expires_at` window, and a single-use nonce, signed
- (Ed25519) by one of your configured trust anchors. Verification is
- **fail-closed**: a missing, malformed, untrusted, expired, replayed, or
- mismatched proof rejects the registration and writes nothing. Consumed nonces
- are persisted in the database, so replay protection survives server restarts.
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `AM_REGISTRATION_PROOF_GATE_ENABLED` | `false` | Master switch. Off = self-asserted identity (unchanged default). |
- | `AM_REGISTRATION_PROOF_TRUSTED_KEYS` | (empty) | Comma-separated base64 Ed25519 public keys (32 raw bytes each). Enabled with no keys = every registration fails closed. |
- | `AM_REGISTRATION_PROOF_MAX_LIFETIME_SECONDS` | `300` | Maximum allowed `expires_at - issued_at` window. |
- | `AM_REGISTRATION_PROOF_CLOCK_SKEW_SECONDS` | `60` | Clock-skew tolerance for the validity window. |
- | `AM_REGISTRATION_PROOF_REQUIRE_NONCE` | `true` | Require and consume a single-use nonce per proof (replay protection). |
- The canonical signing bytes (v2) are explicit, so issuers can be written in any
- language. They are LF-terminated lines:
- 1. `agent-mail-registration-proof:v2`.
- 2. `identity`, `project_key`, `program` and `model`, in that order. Each is
- `label=N:value`, where N is the value's UTF-8 byte length; values are neither
- escaped nor trimmed.
- 3. `capabilities=N` with the count, then one `capability=N:value` line per
- capability (trimmed, non-empty, sorted by bytes, de-duplicated).
- 4. `issued_at=N` and `expires_at=N` as decimal i64.
- 5. `nonce=N:value`.
- v1 proofs (`field=value` lines without length prefixes) are rejected; reissue
- them. Verification is expressed through a
- pluggable `ProofVerifier` trait (`crates/mcp-agent-mail-tools/src/proof_gate.rs`);
- the shipped implementation is the Ed25519 trust-anchor verifier, and external
- verifier backends can be added without touching registration call sites.
- ---
- ## Architecture
- Cargo workspace with strict dependency layering:
- ```text
- MCP Client / Operator / Browser
- │ │ │
- ├─ stdio ───┤ │
- ├─ HTTP ───┼───────────┤
- ▼ ▼ ▼
- mcp-agent-mail-server
- │
- ┌────────────┼────────────┬─────────────┐
- ▼ ▼ ▼ ▼
- 45 MCP Tools 25 Resources TUI Web UI
- │ │ │ │
- └────────────┴──────┬─────┴─────────────┘
- ▼
- mcp-agent-mail-tools
- │
- ┌──────────┼──────────┬──────────────┐
- ▼ ▼ ▼ ▼
- mcp-agent-mail-db storage search-core share/export
- (SQLite index) (Git) (query path) (bundles/static)
- │
- mcp-agent-mail-core
- (config, models, errors, metrics)
- ```
- ### Workspace Structure
- ```
- mcp_agent_mail_rust/
- ├── Cargo.toml # Workspace root (12 member crates; dashboard-wasm is excluded and built standalone)
- ├── crates/
- │ ├── mcp-agent-mail-core/ # Zero-dep: config, models, errors, metrics
- │ ├── mcp-agent-mail-db/ # SQLite schema, queries, pool, cache, Search V3 integration
- │ ├── mcp-agent-mail-storage/ # Git archive, commit coalescer, notification signals
- │ ├── mcp-agent-mail-search-core/ # Pluggable search traits
- │ ├── mcp-agent-mail-guard/ # Pre-commit guard, reservation enforcement
- │ ├── mcp-agent-mail-share/ # Snapshot, scrub, bundle, crypto, export
- │ ├── mcp-agent-mail-tools/ # 45 MCP tool implementations (9 clusters)
- │ ├── mcp-agent-mail-server/ # HTTP/MCP runtime, dispatch, TUI (16 screens)
- │ ├── mcp-agent-mail/ # Server binary (mcp-agent-mail)
- │ ├── mcp-agent-mail-cli/ # CLI binary (am) with robot mode
- │ ├── mcp-agent-mail-test-helpers/ # Shared test scaffolding
- │ ├── mcp-agent-mail-dashboard-wasm/ # Standalone public DashboardScreen WASM replay + safe exporter (excluded from the workspace)
- │ └── mcp-agent-mail-conformance/ # Python parity tests
- ├── experimental/
- │ └── mcp-agent-mail-wasm/ # Parked standalone WASM/browser prototype
- ├── tests/e2e/ # End-to-end test scripts
- ├── scripts/ # CLI integration tests, utilities
- ├── docs/ # ADRs, specs, runbooks, migration guides
- ├── install.sh # Unix installer
- ├── install.ps1 # Windows PowerShell installer
- └── rust-toolchain.toml # Nightly toolchain requirement
- ```
- ### Canonical File Layout
- The runtime uses several paths whose defaults have evolved across versions.
- This table resolves the three-way ambiguity:
- | Path | Purpose | Notes |
- |------|---------|-------|
- | `~/.mcp_agent_mail_git_mailbox_repo/` | Legacy archive root (pre-v1) | No longer created; honored if it already exists on disk |
- | `$XDG_DATA_HOME/mcp-agent-mail/git_mailbox_repo/` | Current archive root (`STORAGE_ROOT` default) | `~/.local/share/mcp-agent-mail/git_mailbox_repo/` on most Linux systems |
- | `$XDG_CONFIG_HOME/mcp-agent-mail/config.env` | Canonical env file (installer writes here) | `~/.config/mcp-agent-mail/config.env` on most Linux systems |
- | `$XDG_CONFIG_HOME/mcp-agent-mail/.env` | Compatibility env file | Checked when `config.env` is absent |
- | `~/.mcp_agent_mail/.env` | Legacy env file | Checked after XDG paths |
- | `<STORAGE_ROOT>/storage.sqlite3` | Runtime database (`DATABASE_URL` default) | Inside the archive root unless `DATABASE_URL` is set |
- The `STORAGE_ROOT` resolution logic: if the legacy path `~/.mcp_agent_mail_git_mailbox_repo/`
- exists on disk, it is used for backward compatibility. Otherwise the XDG data
- directory is preferred. Override with `STORAGE_ROOT=/your/path` in the environment.
- ### Storage Layout (inside STORAGE_ROOT)
- ```
- $STORAGE_ROOT/ # e.g. ~/.local/share/mcp-agent-mail/git_mailbox_repo/
- ├── projects/
- │ └── {project_slug}/
- │ ├── .git/ # Per-project git repository
- │ ├── messages/
- │ │ └── {YYYY}/{MM}/ # Date-partitioned canonical messages
- │ ├── agents/
- │ │ └── {agent_name}/
- │ │ ├── inbox/ # Agent inbox copies
- │ │ └── outbox/ # Agent outbox copies
- │ ├── build_slots/ # Build slot leases (JSON)
- │ └── file_reservations/ # Reservation artifacts
- └── .archive.lock # Global advisory lock
- ```
- ### Key Design Decisions
- - **Git-backed archive** for human auditability; SQLite as fast index
- - **WAL mode** with PRAGMA tuning and connection pooling for concurrent access
- - **Write-behind cache** with dual-indexed ReadCache and deferred touch batching (30s flush)
- - **Async git commit coalescer** (write-behind queue) to avoid commit storms
- - **i64 microseconds** for all timestamps (no `chrono::NaiveDateTime` in storage layer)
- - **Search V3**: portable lexical retrieval uses the local `TantivyBridge`; optional FrankenSearch semantic retrieval and hybrid fusion compile through the `hybrid` feature and run only with `AM_SEARCH_SEMANTIC_ENABLED=true`. Portable builds and the default runtime keep the deterministic lexical path.
- - **Compatibility testing** against intentionally retained Python wire contracts,
- plus Rust-native durability and behavior fixtures. The Rust implementation is
- authoritative; legacy parity never overrides reliability, security, bounded
- work, or structured-concurrency invariants.
- - **Advisory file reservations** with symmetric fnmatch, archive reading, and rename handling
- - **`#![forbid(unsafe_code)]`** across all crates
- - **Query-only read lane** — direct mailbox reads use an existing live SQLite pool and do not wait for archive reconstruction or write-behind coalescing
- - **Evidence-bearing timeouts** — timeout responses and health output expose the measured stage and latency evidence instead of assigning generic database blame
- - **asupersync exclusively** for all async operations (no Tokio, reqwest, hyper, or axum)
- ---
- ## ATC Learning Implementation Map
- > **Validated ATC learning loop — rollout remains gated by write mode.**
- >
- > ATC now has a durable live-learning path: hot-path `atc_note_*` hooks append experience rows, real runtime signals resolve outcomes, rollups/retention/replay are implemented, and robot/TUI surfaces consume the shared live operator snapshot. `AM_ATC_WRITE_MODE` still gates rollout (`off` default, `shadow` for observation, `live` for durable writes), so broader promotion remains operator-controlled rather than always-on. Treat the map below as the current ownership contract and rollout/hardening guide, not as a future-only blueprint.
- The `br-0qt6e` ATC learning work is intentionally cross-cutting, but it should not be cross-owned. The codebase already has the right seams; future implementation should deepen those seams instead of spreading ATC state across tools, UI layers, or ad-hoc SQL in random crates.
- ### Ownership by crate and module
- | Area | Current modules | Owns | Must not own |
- |------|------------------|------|--------------|
- | Core contract | `crates/mcp-agent-mail-core/src/experience.rs`, `evidence_ledger.rs`, `atc_baseline.rs`, `config.rs` | Canonical `ExperienceRow` shape, lifecycle transitions, feature vector/extension schema, decision/evidence identifiers, frozen pre-learning baseline, env/config surface | SQL persistence, archive writes, UI-specific formatting |
- | SQLite persistence | `crates/mcp-agent-mail-db/src/schema.rs` (v16 `atc_experiences`, `atc_experience_rollups`) | Durable raw experience rows, open-resolution lookup indexes, stratum rollups, retention/compaction mechanics, future insert/resolve/query APIs | Decision policy, ATC tick logic, web/TUI rendering |
- | Git/archive boundary | `crates/mcp-agent-mail-storage/src/lib.rs` | Human-auditable artifact writes, WBQ/commit coalescing, selected policy/audit artifacts when explicitly promoted | Raw ATC experience exhaust; the current `WriteOp` surface intentionally handles message, reservation, profile, and notification artifacts, not learning-row mirroring |
- | ATC runtime | `crates/mcp-agent-mail-server/src/atc.rs` | Decision engine, liveness/conflict/routing/calibration math, policy bundle loading, global ATC singletons, tick loop, outcome feedback, summary snapshots | Direct SQLite schema ownership, long-lived CLI state, alternate UI-specific models |
- | Runtime wiring | `crates/mcp-agent-mail-server/src/lib.rs` | Bootstrapping via `init_global_atc()` and `start_atc_operator_runtime()`, tool-dispatch liveness hooks via `atc_register_agent_with_project()` and `atc_observe_activity_with_project()`, shared ATC operator snapshot publication | Per-tool bespoke learning persistence; tool handlers should emit domain facts, not become the learning store |
- | Agent/operator surfaces | `crates/mcp-agent-mail-cli/src/robot.rs`, `crates/mcp-agent-mail-server/src/tui_screens/system_health.rs`, `tui_web_dashboard.rs`, `/mail/ws-state` | Rendering the shared ATC/operator snapshot for robot and live TUI consumers; reserved browser-mirror modules stay read-only/non-owning and fall back to local heuristics only when live server state is unavailable | Independent ATC truth, separate persistence, or duplicate learning logic |
- | Tool/resource layer | `crates/mcp-agent-mail-tools/src/*`, `crates/mcp-agent-mail-tools/src/resources.rs` | Normal tool/resource contracts for mailbox coordination; ATC-adjacent work should surface through existing runtime hooks and shared snapshots | Owning ATC learning state machines or experience-row lifecycle rules |
- ### Append and resolution hooks
- - Session/bootstrap and liveness hooks already land at the server dispatch boundary: successful `register_agent` and `macro_start_session` calls register agents with ATC, and tool execution updates ATC activity timestamps.
- - The durable append path now belongs in that same server/runtime seam, not inside individual UIs. Message and reservation learning hooks flow from the tool-result/event boundary in `mcp-agent-mail-server/src/lib.rs` into the ATC-facing note functions in `mcp-agent-mail-server/src/atc.rs`: `atc_note_message_sent()`, `atc_note_message_received()`, `atc_note_reservation_granted()`, `atc_note_reservation_released()`, and `atc_note_reservation_conflicts()`.
- - Outcome resolution now flows through the server ATC runtime: message outcomes are resolved from the tool-result boundary (`record_atc_message_outcome_from_tool_payload_with_pool` in `mcp-agent-mail-server/src/lib.rs`) plus the overdue/retention sweeps, with the DB crate owning the actual row mutation and rollup updates. (`atc_record_outcome()` in `atc.rs` is the in-memory engine hook and currently has no production caller.)
- - `/mail/ws-state` polling, `am robot atc`, the ATC TUI screen, and the System Health screen stay snapshot-driven consumers of `atc_operator_snapshot()` / `atc_summary()`, not alternate sources of learning state. The deferred `/web-dashboard/*` browser mirror is intentionally outside the supported live ATC surface today.
- ### Hot path vs. cold path boundaries
- - Hot path: `mcp-agent-mail-server/src/atc.rs`, the tool-dispatch hook in `mcp-agent-mail-server/src/lib.rs`, and the DB append/resolve calls behind `AM_ATC_WRITE_MODE`. This path must stay append-friendly, bounded, and free of Git write amplification.
- - Warm path: ATC operator snapshots, `/mail/ws-state` polling, `am robot atc`, and the TUI/System Health surfaces. These consumers should read already-computed ATC state and only fall back to local heuristics when the live server snapshot is unavailable. The deferred `/web-dashboard/*` mirror is intentionally excluded from the live warm path until a future resurrection effort lands.
- - Cold path: promoted policy bundles, transparency cards, replay artifacts, and operator-facing audit bundles. These may be written through `mcp-agent-mail-storage`, but only after they are intentionally compacted and selected.
- - Explicit non-owner boundary: `mcp-agent-mail-search-core`, share/export, and the WASM/browser mirror are consumers or transport layers. They should not become the canonical home of ATC learning policy, persistence, or attribution logic.
- ### Verification ownership
- - `crates/mcp-agent-mail-core/src/experience.rs`: unit/property coverage for lifecycle validity, feature-vector stability, serialization, and idempotent resolution transitions.
- - `crates/mcp-agent-mail-db/src/schema.rs` plus the ATC DB query modules: migration coverage, insert/resolve semantics, rollup correctness, retention/compaction tests, and replay/reconstruct safety.
- - `crates/mcp-agent-mail-server/src/atc.rs`: decision math, policy-bundle loading, safe-mode transitions, tick budgeting, and feedback/calibration tests.
- - `crates/mcp-agent-mail-server/src/lib.rs`, `tui_ws_state.rs`, `tui_screens/system_health.rs`, and `crates/mcp-agent-mail-cli/src/robot.rs`: snapshot publication, route contracts, robot fallback behavior, and operator-surface rendering tests.
- - `tests/e2e/` and performance harnesses: live-server E2E plus soak/perf coverage validate that ATC learning stays low-write-amplification and does not regress request/tick budgets.
- ### Rollout and hardening priorities
- 1. Keep `mcp-agent-mail-core` as the schema-and-policy contract so experience/evidence/config changes stay centralized and reviewable.
- 2. Preserve `mcp-agent-mail-db` as the only durable ATC mutation/query surface for append, resolve, rollup, retention, and replay behavior.
- 3. Continue routing real runtime events through `atc_note_*` and the server-side outcome-resolution path instead of duplicating learning logic in tools, UIs, or ad-hoc SQL paths.
- 4. Keep robot, TUI, and browser/dashboard surfaces snapshot-driven consumers of `atc_operator_snapshot()` rather than alternate sources of ATC truth.
- 5. Land remaining rollout/default-flip, data-minimization, and operator-hardening work on top of the existing live path rather than reopening seam ownership questions.
- ---
- ## Core Data Model
- | Type | Role |
- |------|------|
- | `Project` | Stable identity for one codebase, keyed by absolute path and slug |
- | `Product` | Cross-project grouping for search, inbox aggregation, and routing |
- | `Agent` | Registered worker identity with name, program, model, policy, and task metadata |
- | `Message` | Canonical envelope for subject, body, importance, thread, attachments, and recipients |
- | `Recipient` | Delivery metadata for `to`/`cc`/`bcc`, read state, and acknowledgement state |
- | `Thread` | Logical conversation identifier spanning replies and summaries |
- | `FileReservation` | Advisory lease over file paths/globs with TTL, exclusivity, and reason |
- | `BuildSlot` | Named lease used to serialize build-heavy work on a shared checkout |
- | `ToolMetrics` | Per-tool latency, error, and call-count telemetry used by TUI, CLI, and diagnostics |
- The important boundary is this: Git stores the durable human-auditable artifacts, while SQLite stores the queryable operational state. Every surface in the project is built around that split.
- ---
- ## How the System Works
- ### Write Path
- 1. An MCP tool call, CLI command, web overseer action, or guard hook enters the runtime.
- 2. Inputs are normalized and validated against project identity, agent names, and policy constraints.
- 3. The SQLite layer performs the indexed mutation: insert/update rows, enforce invariants, and emit IDs/timestamps.
- 4. The storage layer writes canonical Markdown/JSON artifacts into the per-project archive.
- 5. The commit coalescer batches archive updates so bursts of activity do not become commit storms.
- 6. Metrics and event streams are updated so TUI, robot, and web surfaces all observe the same fresh state.
- ### Read Path
- 1. A resource read, robot command, TUI view, or web request asks for mailbox or tooling state.
- 2. The server resolves scope: project, agent, product, thread, search query, or tooling view.
- 3. For direct state, an existing live SQLite mailbox answers through a query-only lane; it does not wait for archive reconstruction or the write-behind coalescer, and a read request does not create a missing project. `fetch_inbox` performs its optional read-receipt update separately after the bounded read. For search, Search V3 plans the query and executes the appropriate lexical route, or the semantic/hybrid route when the `feature = "hybrid"` build path is compiled in and `AM_SEARCH_SEMANTIC_ENABLED=true`.
- 4. The result is rendered as MCP JSON, robot `toon`/`json`/`md`, TUI widgets, or HTML under `/mail/`.
- That consistency comes from a shared DB + archive + metrics pipeline. The TUI, web UI, robot CLI, and MCP resources are separate renderers over the same underlying state.
- ---
- ## Search Architecture
- Search V3 is not an afterthought bolted onto mailbox rows. It is a dedicated query path with shared planning and diagnostics:
- - Queries are normalized, classified, and routed through a unified search service.
- - Lexical mode provides the baseline contract and diagnostics surface; semantic and hybrid modes extend that contract in a `hybrid`-feature build with `AM_SEARCH_SEMANTIC_ENABLED=true`. Otherwise a semantic, hybrid, or auto request runs lexical.
- - Candidate budgeting and fusion keep broad natural-language queries from exploding while preserving exact-match strength for identifiers and short phrases.
- - The same search path serves MCP tools, `am mail search`, `am robot search`, TUI search, and web UI search routes.
- - Empty or non-searchable queries route through a deterministic SQL plan before Search V3 candidate retrieval. Legacy SQLite FTS artifacts still exist for migration hygiene and cleanup, but the current search architecture is Search V3 plus that deterministic SQL plan, not a hidden FTS fallback.
- The dedicated `mcp-agent-mail-search-core` crate exists specifically so search planning and backends can evolve without entangling the rest of the mailbox stack.
- ---
- ## Coordination Algorithms and Safety Invariants
- - **Explicit recipients only.** `send_message` keeps a `broadcast` field for schema compatibility, but `broadcast=true` is intentionally rejected so agents cannot spam every other agent by default.
- - **Project isolation first.** Agent names are only meaningful inside a project unless a contact link or product bus path explicitly bridges them.
- - **Symmetric reservation matching.** File reservation conflicts use symmetric glob overlap checks, so `src/**` conflicts with `src/lib.rs` in either direction.
- - **TTL instead of forever-locks.** Reservations and build slots expire, which makes the system robust to crashed or vanished agents.
- - **Wrong-surface denial.** MCP-only and CLI-only commands fail deterministically when invoked through the wrong entrypoint, reducing automation footguns.
- - **Idempotent session bootstrapping.** `ensure_project`, `register_agent`, and the session macros are designed so agents can safely retry startup without creating duplicate identity state.
- - **Durable monitor cursors.** Inbox-event consumers advance a recipient delivery cursor only after handling an oldest-first page; a message ID is never a safe cursor substitute.
- - **Contact approval as policy, not convention.** Cross-project messaging is gated by explicit contact workflows and per-agent contact policies.
- These are the design rules that let many agents share one checkout without immediately degenerating into chaos.
- ---
- ## Consistency and Recovery Model
- - **SQLite is the live operational state.** MCP tools, resources, the TUI, the web UI, and robot/CLI reads use SQLite for current inboxes, message IDs, read/ack state, reservations, agents, products, and search planning.
- - **Git is the durable artifact ledger.** Canonical messages, inbox/outbox copies, reservation files, and agent profiles are written as files under per-project archives so the mailbox remains human-auditable and recoverable.
- - **Concurrent writes are queued, not hand-merged.** Parallel agents can send to the same thread at the same time; the server/DB layer serializes the indexed mutations, and the archive write-behind queue plus commit coalescer batches the corresponding Git artifact writes. There is no workflow where two agents create a Git merge conflict and a human resolver has to pick the winning message.
- - **Reservation artifacts have a database generation.** A new physical SQLite database gets a new generation token, so its reservation row IDs cannot overwrite a prior generation's archive artifacts. Foreign stamped artifacts remain inspectable without being treated as live parity drift.
- - **Repair is not reconstruct.** `am doctor repair` is the in-place hygiene path. `am doctor reconstruct` is the archive-first rebuild path when SQLite is no longer trustworthy.
- - **Backups are first-class.** `archive save`, doctor backups, and restore flows all exist because operational recovery is part of the product, not a manual afterthought.
- - **Stale lock cleanup is expected.** Guard hooks, archive lock management, and doctor checks assume agents crash and processes die unexpectedly.
- If the live layer gets sick, the durable ledger can rebuild it.
- ---
- ## Comparison vs. Alternatives
- | Feature | MCP Agent Mail | Shared Files / Lockfiles | Custom MCP Tools | Chat-Based Coordination |
- |---------|---------------|-------------------------|------------------|------------------------|
- | Agent identity & discovery | Persistent names, profiles, directory queries | None | Manual | Ephemeral |
- | Threaded messaging | Subjects, CC/BCC, ack, importance, search | N/A | Build yourself | Linear chat, no structure |
- | File reservation / advisory locks | Glob patterns, TTL, exclusive/shared, pre-commit guard | Lockfiles (no TTL, no glob) | Build yourself | None |
- | Audit trail | Full Git history of all communication | File timestamps | Depends | Chat logs (if saved) |
- | Cross-repo coordination | Product bus, contact system | Manual | Build yourself | Manual |
- | Search | Search V3 (lexical in release binaries; semantic + hybrid in default-feature source builds) | `grep` | Build yourself | Limited |
- | Operational visibility | 16-screen TUI, robot CLI, metrics | None | None | None |
- | Token efficiency | Messages stored externally, not in context | Files in context | Varies | All in context |
- ---
- ## Development
- ```bash
- # Quality gates
- cargo fmt --check
- cargo clippy --workspace --all-targets -- -D warnings
- cargo check --workspace --all-targets
- cargo test --workspace
- # Compatibility and Rust-native conformance tests
- cargo test -p mcp-agent-mail-conformance
- # Run specific crate tests
- cargo test -p mcp-agent-mail-db
- cargo test -p mcp-agent-mail-tools
- cargo test -p mcp-agent-mail-server
- # E2E tests
- tests/e2e/test_stdio.sh # MCP stdio transport
- tests/e2e/test_http.sh # HTTP transport
- tests/e2e/test_guard.sh # Pre-commit guard
- tests/e2e/test_macros.sh # Macro tools
- tests/e2e/test_share.sh # Share/export
- tests/e2e/test_dual_mode.sh # Mode switching
- scripts/e2e_cli.sh # CLI integration (99 assertions)
- # Native E2E runner (authoritative path)
- am e2e list
- am e2e run --project . # all suites
- am e2e run --project . stdio http # selected suites
- am e2e run --project . --include tui_ # pattern include
- am e2e run --project . tui_full_traversal # traversal + flash + soak regression gate
- am e2e run --project . --tag reliability --release-scorecard # reliability release gate
- # ^ runs every @tags: reliability suite (incl. the incident_corpus harness) and writes
- # tests/artifacts/release_scorecard/<ts>/release_scorecard.json (per-suite rows +
- # per-incident-class rows with anchors + a combined release_ready verdict)
- # Legacy compatibility shim (deprecated primary path)
- ./scripts/e2e_test.sh stdio
- # rollback guard: AM_E2E_FORCE_LEGACY=1 ./scripts/e2e_test.sh stdio
- # Benchmarks
- cargo bench -p mcp-agent-mail
- # Multi-agent builds: offload heavy cargo work through rch
- rch exec -- cargo check --workspace --all-targets
- # Shared-checkout verification lanes: acquire a build slot, run through rch, preserve logs
- am verify cargo-check --path . --agent AgentName --block-on-conflicts
- am verify cargo-clippy --path . --agent AgentName --block-on-conflicts
- am verify cargo-test --path . --agent AgentName --block-on-conflicts
- am verify e2e-stdio --path . --agent AgentName --block-on-conflicts
- am verify bench-quick --path . --agent AgentName --block-on-conflicts
- ```
- `am verify` is a thin `am-run` lane mapper. It always shows the exact command, uses a `verify-*` build slot even when `WORKTREES_ENABLED` is not set in the shell, routes cargo-heavy work through `rch exec -- ...`, and writes `command.json`, `stdout.log`, `stderr.log`, `exit_code.txt`, and `result.json` under `STORAGE_ROOT/artifacts/verify/<timestamp>-<lane>/` unless `--artifact-dir` is supplied.
- `result.json` includes `rch_proof.status`, `child_exit_code`, and the final proof `exit_code`. For `rch exec` lanes, a zero-exit child is only green when the captured output includes a positive remote-execution marker. Local fallback or missing remote proof fails closed, writes `rch_proof_failure.txt`, and best-effort captures `rch_status_workers.json` plus `rch_queue.json` so operators can distinguish a remote test failure from transport/sync/fleet degradation.
- Release evidence for robot/doctor fields must prove the installed `am` binary, not only the source-built test binary. For parity-sensitive fields such as `forensic_timeline`, search-index health, recovery status, artifact links, next actions, and redaction, run the installed-binary parity gate against the release candidate installed on the same host or remote worker:
- ```bash
- AM_INSTALLED_BINARY_PARITY_BIN=/path/to/installed/am \
- rch exec -- cargo test -p mcp-agent-mail-cli --test it \
- integration_runs::installed_binary_parity_probe_compares_source_and_installed_am -- --ignored --nocapture
- ```
- The gate writes `tests/artifacts/installed_binary_parity/<run>/parity_report.json` with one pass/fail row per required JSON path, redacted source/installed values, value-mismatch status, and redacted command metadata. If the candidate lacks fields that source tests rely on, or returns different required values, the report is red and the release is not closed. A local direct `am doctor check --json` or `am robot ... --format json` probe is useful for quick inspection, but it is not sufficient release evidence unless paired with this parity report and an `rch exec -- ...` cargo proof.
- Use `--dry-run` to inspect the lane without running it. Use `--no-block-on-conflicts` only when the slot conflict is understood and you intentionally want advisory behavior.
- ### E2E Entrypoint Policy (T9.9)
- - Native `am e2e` is authoritative for operator and CI invocation.
- - `scripts/e2e_test.sh` remains compatibility-only and emits deprecation guidance.
- - Rollback condition: set `AM_E2E_FORCE_LEGACY=1` only if native runner regression is confirmed.
- Verification checklist:
- - `am e2e list` and `am e2e run --project . <suite>` succeed for targeted suites.
- - Artifact repro commands reference `am e2e run` (not script-first commands).
- - CI/release docs and runbooks do not present `scripts/e2e_test.sh` as the primary command.
- ### Verification Realism Policy
- The canonical realism and closure policy lives in [docs/VERIFICATION_COVERAGE_LEDGER.md](/data/projects/mcp_agent_mail_rust/docs/VERIFICATION_COVERAGE_LEDGER.md).
- - `R0` and `R1` are the lanes that carry closure weight.
- - `R2` and `R3` substitutes are second-best evidence and must name their compensating real-path coverage.
- - Stub-only lanes do not close transport, persistence, install/update, search-quality, LLM-quality, crypto/share, or operator-surface claims by themselves.
- ### Key Dependencies
- | Crate | Purpose |
- |-------|---------|
- | `asupersync` | Structured async runtime (channels, sync, regions, HTTP, testing) |
- | `fastmcp-rust` / `fastmcp` | MCP protocol implementation (JSON-RPC, stdio, HTTP transport) |
- | `sqlmodel_rust` / `sqlmodel` | SQLite ORM (schema, queries, migrations, pool) |
- | `frankentui` | TUI rendering (widgets, themes, accessibility, markdown, syntax highlighting) |
- | `frankensearch` | Hybrid search engine (lexical + semantic, two-tier fusion, reranking) |
- | `br` (external CLI) | Issue tracking integration |
- | `toon` | Token-efficient compact encoding for robot mode output |
- ---
- ## Performance and Benchmarking
- The repository carries both stress tests and reproducible benchmark baselines. The two serve different purposes:
- - **Stress suites** answer “does the system stay correct under ugly concurrency?”
- - **Bench suites** answer “how fast is the operator and mailbox path right now?”
- ### Native `am bench`
- The native CLI benchmark runner is built around four categories in `crates/mcp-agent-mail-cli/src/bench.rs`:
- | Category | Built-in cases | What it measures |
- |----------|----------------|------------------|
- | Startup | `help` | Pure CLI startup and argument parsing |
- | Analysis | `lint`, `typecheck` | Cost of native quality commands |
- | Stub encoder | `stub_encode_1k`, `stub_encode_10k`, `stub_encode_100k` | Compact encoding subprocess path |
- | Operational | `mail_inbox`, `mail_send`, `mail_send_no_atc`, `mail_send_atc_shadow`, `mail_send_atc_live`, `mail_search`, `robot_status`, `doctor_check`, `message_count`, `agents_list` | Real mailbox/operator workflows over a seeded DB (`am bench --list` is authoritative) |
- ### Checked-In Baselines
- These numbers come from [`benches/BUDGETS.md`](benches/BUDGETS.md), which records dated benchmark baselines and budgets.
- #### CLI Operational Baselines (`am bench --quick`, 2026-02-09)
- | Command | Baseline mean | Budget |
- |---------|---------------|--------|
- | `am --help` | 4.2ms | < 10ms |
Lines 2,001–2,451 are not shown. The link to the file on GitHub has every line.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.