MCP Agent Mail (Rust)

"It's like Gmail for your coding agents!"

A mail-like coordination layer for AI coding agents, exposed as an MCP server with 37 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 (1,700+ stars).

Supported agents: Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, and any MCP-compatible client.

Watch the 23-minute walkthrough to see seven AI coding agents send over 1,000 messages to each other while implementing a development plan over two days.

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcpagentmail_rust/main/install.sh?$(date +%s)" | bash

Table of Contents

• TL;DR
• Why This Exists
• What People Are Saying
• Design Philosophy
• Rust vs. Python: Stress Test Results
• Installation
• Quick Start
• Agent Configuration
• Server Modes
• Operator CLI Surface
• The 37 MCP Tools
• TUI Operations Console
• Robot Mode (am robot)
• File Reservations
• Multi-Agent Coordination Workflows
• Web UI
• Deployment Validation
• Configuration
• Architecture
• ATC Learning Implementation Map
• Core Data Model
• How the System Works
• Search Architecture
• Coordination Algorithms and Safety Invariants
• Consistency and Recovery Model
• Comparison vs. Alternatives
• Development
• Performance and Benchmarking
• Mailbox Diagnostics (am doctor)
• Troubleshooting
• Limitations
• FAQ
• Appendix: Protocol Transcript
• Appendix: TUI vs. Web vs. Robot
• Documentation
• About Contributions
• 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 | | 37 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 | 18 agent-optimized CLI subcommands with toon/json/md output for non-interactive workflows | | Git-Backed Archive | Every message, reservation, and agent profile stored as files in per-project Git repos | | Hybrid Search | Search V3 via frankensearch. The lexical tier ships by default; semantic and hybrid routing are controlled by the hybrid feature flag (feature = "hybrid"). | | 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

# Install and start (auto-detects all installed coding agents)
am
That's it. Server starts on 127.0.0.1:8765 with the interactive TUI.
Agents coordinate through MCP tools:
  ensureproject(humankey="/abs/path")
  registeragent(projectkey="/abs/path", program="claude-code", model="opus-4.6")
  filereservationpaths(projectkey="/abs/path", agentname="BlueLake", paths=["src/**"], ttl_seconds=3600, exclusive=true)
  sendmessage(projectkey="/abs/path", sendername="BlueLake", to=["GreenCastle"], subject="Starting refactor", bodymd="Taking src/**", thread_id="FEAT-123")
  fetchinbox(projectkey="/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 and bv 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 37 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 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 31 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 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

"Agent mail is a truly brain-melting experience the first time. Thanks for building it."

— @quastora

"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

"Use it with agent mail == holy grail."

— @metapog

"The only correct answer to this is mcp agent mail."

— @skillcreatorai

"GPT 5.2 suggesting beads + agent mail for agent co-ordination (of course, I am already using them)."

— @jjpcodes

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 always override if needed. Deadlocks become impossible while accidental conflicts still get caught. Reservations expire on a TTL, so crashed agents don't hold files hostage forever.

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 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 was designed specifically to eliminate these, and a dedicated stress test suite proves it.

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

• Git lock contention eliminated. The commit coalescer batches rapid-fire writes into far fewer git commits (9.1x reduction observed). Lock-free git plumbing commits avoid index.lock entirely in most cases.
• Pool exhaustion handled gracefully. Even with 4x more threads than pool connections (60 vs 15), all 600 operations succeeded with 0 timeouts. WAL mode + 60s busy_timeout lets writers queue rather than fail.
• 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.

Installation

One-Liner (recommended)

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcpagentmail_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. Supports --verify for checksum + Sigstore cosign verification.

Options: --version vX.Y.Z, --dest DIR, --system (installs to /usr/local/bin), --from-source, --verify, --easy-mode (auto-update PATH), --force, --uninstall, --yes, --purge.

Windows One-Liner (PowerShell)

iwr -useb "https://raw.githubusercontent.com/Dicklesworthstone/mcpagentmail_rust/main/install.ps1?$(Get-Random)" | iex

PowerShell options: -Version vX.Y.Z, -Dest PATH, -Force.

From Source

git clone https://github.com/Dicklesworthstone/mcpagentmail_rust
cd mcpagentmail_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 CARGOTARGETDIR overrides or workspace settings. Do not manually copy from target/release/am -- if CARGOTARGETDIR is set, that path may be stale.

Requires Rust nightly (see rust-toolchain.toml). Source builds also expect locally patched sibling checkouts in the parent directory for seven repos: ../asupersync, ../fastmcprust, ../beadsrust, ../sqlmodel_rust, ../frankensqlite, ../frankentui, and ../frankensearch.

Platforms

| Platform | Architecture | Binary | |----------|-------------|--------| | Linux | x8664 | mcp-agent-mail-x8664-unknown-linux-gnu | | Linux | aarch64 | mcp-agent-mail-aarch64-unknown-linux-gnu | | macOS | x8664 | mcp-agent-mail-x8664-apple-darwin | | macOS | Apple Silicon | mcp-agent-mail-aarch64-apple-darwin | | Windows | x8664 | mcp-agent-mail-x8664-pc-windows-msvc.zip |

Quick Start

1. Start the server

am

Auto-detects all installed coding agents (Claude Code, Codex CLI, Gemini CLI, etc.), refreshes their MCP connections as needed, and starts the HTTP server on 127.0.0.1:8765 with the interactive TUI.

2. Agents register and coordinate

Once the server is running, agents use MCP tools to coordinate:

Terminology note: ensureproject takes a humankey, 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
ensureproject(humankey="/abs/path/to/repo")
registeragent(projectkey="/abs/path/to/repo", program="claude-code", model="opus-4.6")
Reserve files before editing
filereservationpaths(projectkey="/abs/path/to/repo", agentname="GreenCastle", paths=["src/**"], ttl_seconds=3600, exclusive=true)
Send a message
sendmessage(projectkey="/abs/path/to/repo", sender_name="GreenCastle", to=["BlueLake"],
             subject="Starting auth refactor", body_md="Taking src/auth/**",
             threadid="FEAT-123", ackrequired=true)
Check inbox
fetchinbox(projectkey="/abs/path/to/repo", agent_name="BlueLake")
acknowledgemessage(projectkey="/abs/path/to/repo", agentname="BlueLake", messageid=123)

3. Use macros for common flows

# Boot a full session (ensure project + register agent + reserve files + fetch inbox)
macrostartsession(human_key="/abs/path/to/repo", program="claude-code", model="opus-4.6")
Prepare for a thread (fetch context + recent messages)
macropreparethread(projectkey="/abs/path/to/repo", threadid="FEAT-123",
                     program="claude-code", model="opus-4.6")
Reserve, work, release cycle
macrofilereservationcycle(projectkey="/abs/path/to/repo", agent_name="GreenCastle",
                             paths=["src/auth/**"], ttlseconds=3600, autorelease=true)
Contact handshake between agents in different projects
macrocontacthandshake(project_key="/abs/path/to/repo", requester="GreenCastle",
                        target="BlueLake", to_project="/abs/path/to/other/repo",
                        autoaccept=true, welcomesubject="Coordination channel",
                        welcome_body="Use thread FEAT-123 for the cutover")

Agent Configuration

The installer and am command auto-detect installed agents. If you used the curl installer, detected Codex CLI configs are written automatically in HTTP URL mode; the examples below are the manual fallback.

Claude Code

Add to your project's .mcp.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "agent-mail": {
      "command": "mcp-agent-mail",
      "args": []
    }
  }
}

Or for HTTP transport (when the server is already running):

{
  "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:

[mcpservers.mcpagent_mail]
url = "http://127.0.0.1:8765/mcp/"
Add this when HTTP bearer auth is enabled:
httpheaders = { Authorization = "Bearer <HTTPBEARER_TOKEN>" }

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "agent-mail": {
      "command": "mcp-agent-mail",
      "args": []
    }
  }
}

For a project-local Gemini setup plus Agent Mail identity registration:

scripts/register_gemini.sh /abs/path/to/repo
AGENTNAME=BlueLake AGENTMODEL=gemini-2.5-pro scripts/register_gemini.sh /abs/path/to/repo

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
• Examples: Token-free client templates live under docs/examples/mcp/

Server Modes

MCP Server (default)

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

am                                      # Auto-detect agents, refresh MCP config, start server + TUI
am serve-http --port 9000               # Different port
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

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 | AMINTERFACEMODE=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 | Start the server, run stdio MCP, manage a background service, or poll inbox state from hooks/editors | | 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 check|archive-scan|archive-normalize|repair|backups|restore|reconstruct|fix | 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. 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 missingfile, legacystdio, stalehttppath, wrongbearerheader, wrongstartuptimeout, duplicateserverentries, and unsupported_config.

Use the reported remediation in two steps:

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 HTTPBEARERTOKEN / 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 | | products | ensure, link, status, search, inbox, summarize-thread | | doctor | check, archive-scan, archive-normalize, repair, backups, restore, reconstruct, fix | | agents | register, create, list, show, detect | | 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 | | 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 |

The 37 MCP Tools

9 Clusters

| Cluster | Count | Tools | |---------|-------|-------| | Infrastructure | 4 | healthcheck, ensureproject, installprecommitguard, uninstallprecommitguard | | Identity | 6 | registeragent, createagentidentity, whois, resolvepaneidentity, cleanuppaneidentities, listagents | | Messaging | 5 | sendmessage, replymessage, fetchinbox, acknowledgemessage, markmessageread | | Contacts | 4 | requestcontact, respondcontact, listcontacts, setcontact_policy | | File Reservations | 4 | filereservationpaths, renewfilereservations, releasefilereservations, forcereleasefile_reservation | | Search | 2 | searchmessages, summarizethread | | Macros | 4 | macrostartsession, macropreparethread, macrocontacthandshake, macrofilereservation_cycle | | Product Bus | 5 | ensureproduct, productslink, searchmessagesproduct, fetchinboxproduct, summarizethreadproduct | | Build Slots | 3 | acquirebuildslot, renewbuildslot, releasebuildslot |

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://filereservations/<project-slug>?activeonly=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: macrostartsession, macropreparethread, macrofilereservationcycle, macrocontact_handshake
• Use granular tools when you need control: registeragent, filereservationpaths, sendmessage, fetchinbox, acknowledgemessage

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 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, / global search focus, . 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 and v for visual selection; Search uses f + facet rail navigation for scope/sort/field controls; Contacts uses n for Table/Graph mode; batch-capable screens share Space/v/A/C; preset-enabled screens use Ctrl+S/Ctrl+L.

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: Cyberpunk Aurora, Darcula, Lumen Light, Nordic Frost, High Contrast. 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.

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.

18 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 | Event stream since last check | --since, --kind, --source | | am robot overview | Cross-project summary | --format, --project, --agent | | am robot thread <id> | Full thread rendering | --limit, --since, --format | | am robot search <query> | Full-text search with facets/relevance | --kind, --importance, --since, --format | | am robot message <id> | Single-message deep view | --format, --project, --agent | | am robot navigate <resource://...> | Resolve resources into robot-formatted output | --format, --project, --agent | | am robot reservations | Reservation view with conflict/expiry awareness | --all, --conflicts, --expiring, --agent | | am robot metrics | Tool call rates, failures, latency percentiles | --format, --project, --agent | | am robot health | Runtime/system diagnostics | --format, --project, --agent, --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 and policy surface | --format, --project, --agent | | am robot projects | Per-project aggregate stats | --format, --project, --agent | | am robot attachments | Attachment inventory and provenance | --format, --project, --agent | | 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 |

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/message-focused): Human-readable narrative for deep context

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

# 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:

filereservationpaths(projectkey, agentname, 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.

| 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/** |

Multi-Agent Coordination Workflows

How Agents Interact (Protocol Flow)

sequenceDiagram
    participant A as Agent A (GreenCastle)
    participant S as Agent Mail Server
    participant B as Agent B (BlueLake)
A->>S: ensureproject(humankey="/abs/path")     A->>S: registeragent(projectkey="/abs/path", program="claude-code")     S-->>A: identity: GreenCastle
B->>S: registeragent(projectkey="/abs/path", program="codex-cli")     S-->>B: identity: BlueLake
A->>S: filereservationpaths(projectkey="/abs/path", agentname="GreenCastle", paths=["src/auth/**"], exclusive=true)     S-->>A: reserved ✓
B->>S: filereservationpaths(projectkey="/abs/path", agentname="BlueLake", paths=["src/auth/**"], exclusive=true)     S-->>B: CONFLICT — reserved by GreenCastle
B->>S: filereservationpaths(projectkey="/abs/path", agentname="BlueLake", paths=["tests/api/**"], exclusive=true)     S-->>B: reserved ✓
A->>S: sendmessage(projectkey="/abs/path", sendername="GreenCastle", to=["BlueLake"], threadid="FEAT-123", ack_required=true)     S-->>B: new message in inbox
B->>S: fetchinbox(projectkey="/abs/path", agent_name="BlueLake")     S-->>B: [message from GreenCastle]
B->>S: acknowledgemessage(projectkey="/abs/path", agentname="BlueLake", messageid=1482)     S-->>A: ack received ✓
A->>S: releasefilereservations(projectkey="/abs/path", agentname="GreenCastle", paths=["src/auth/**"])     S-->>A: released ✓

Same Repository

• Register identity: ensureproject(humankey=<abs-path>) + registeragent(projectkey=<abs-path>, ...)
• Reserve files before editing: filereservationpaths(projectkey, agentname, paths=["src/**"], ttl_seconds=3600, exclusive=true)
• Communicate with threads: sendmessage(..., threadid="FEAT-123"), check with fetchinbox, acknowledge with acknowledgemessage
• Quick reads: resource://inbox/{Agent}?project=<abs-path>&limit=20

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 projectkey. Use macrocontacthandshake to link agents, then message directly. Keep a shared threadid across repos.

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:

# 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

• External tools that opt into the wrapper → coordinated.
• Your IDE running git commit directly, with no wrapper →

The wrapper honors AMGITBINARY for binary selection and AMGITFLOCKTIMEOUTSECS (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 (br) for dependency-aware task selection:

• Pick ready work: br ready --json (choose highest priority, no blockers)
• Reserve edit surface: filereservationpaths(..., reason="br-123")
• Announce start: sendmessage(..., threadid="br-123", subject="[br-123] Start: <title>", ack_required=true)
• Work and update: Reply in-thread with progress
• Complete and release: br close 123, releasefilereservations(...), final Mail reply

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 browser TUI mirror at /web-dashboard is deferred and not a supported surface; see docs/SPEC-browser-parity-contract-deferred.md.

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 search entry point, agent roster, and quick links | | /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}/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: set HTTPBEARERTOKEN for production. For local dev, set HTTPALLOWLOCALHOST_UNAUTHENTICATED=true to browse without headers.

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

Deployment Validation

# 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 | |----------|---------|-------------| | AMINTERFACEMODE | (unset = MCP) | mcp or cli | | HTTP_HOST | 127.0.0.1 | Bind address | | HTTP_PORT | 8765 | Bind port | | HTTP_PATH | /mcp/ | MCP base path | | HTTPBEARERTOKEN | (from .env file) | Auth token | | HTTPALLOWEDHOSTS | (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 | sqlite:///./storage.sqlite3 | SQLite connection URL (relative to working directory) | | AMCACHEPROFILE | balanced | Cache budget preset: conservative, balanced, or high-memory | | DATABASECACHEBUDGET_KB | profile-derived 524288 | Total SQLite page-cache budget across pooled connections, clamped to 16 MiB..4 GiB | | AMREADCACHEENTRIESPER_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 | | ALLOWEPHEMERALPROJECTSINDEFAULTSTORAGE | false | Permit /tmp-style project roots in the default global mailbox archive. Prefer a per-run STORAGEROOT instead. | | LOG_LEVEL | info | Minimum log level | | TUI_ENABLED | true | Interactive TUI toggle | | TUIHIGHCONTRAST | false | Accessibility mode | | AMTUITOAST_ENABLED | true | Enable toast notifications | | AMTUITOAST_SEVERITY | info | Minimum toast severity (info/warning/error/off) | | AMTUITOAST_POSITION | top-right | Toast stack position | | AMTUITOASTMAXVISIBLE | 3 | Max visible toasts at once | | AMTUITOASTINFODISMISS_SECS | 5 | Info toast auto-dismiss timeout | | AMTUITOASTWARNDISMISS_SECS | 8 | Warning toast auto-dismiss timeout | | AMTUITOASTERRORDISMISS_SECS | 15 | Error toast auto-dismiss timeout | | AMTUITHREADPAGESIZE | 20 | Thread conversation page size | | AMTUITHREAD_GUIDES | rounded (theme default) | Thread tree guide style (ascii/unicode/bold/double/rounded) | | AMTUICOACHHINTSENABLED | true | Enable contextual coach-hint notifications | | AMTUIEFFECTS | true | Enable text/animation effects | | AMTUIAMBIENT | subtle | Ambient mode (off/subtle/full) | | AMTUIFULLREDRAWMAX_SECS | 1.0 | Wall-clock bound (seconds) for a guaranteed full TUI redraw that repairs incremental-diff render desync; <= 0 disables the bound | | WORKTREES_ENABLED | false | Build slots feature flag | | INTEGRITYCHECKONSTARTUP | true | Run PRAGMA integritycheck during startup self-heal (set false to fast-unblock a degraded boot) | | STARTUPREADINESSBINDTIMEOUTSECS | 20 | Max seconds to wait for DB readiness before binding the listener anyway (/healthz stays up while the DB warms) | | DBMAINTENANCEENABLED | true | Enable the off-hot-path periodic SQLite maintenance worker (checkpoint/ANALYZE/VACUUM/journal-size cap) | | DBCHECKPOINTINTERVAL_SECS | 300 | Passive WAL checkpoint cadence (0 disables that op) | | DBANALYZEINTERVAL_SECS | 21600 | ANALYZE planner-stats refresh cadence (0 disables) | | DBVACUUMINTERVAL_SECS | 86400 | VACUUM reclaim/defragment cadence (0 disables) | | DBJOURNALSIZELIMITBYTES | 268435456 | journalsizelimit WAL truncation cap (256 MiB) | | AMGITBINARY | (resolver) | Override the git binary for all in-process shell-outs (mitigates the git 2.51.0 index race) | | AMGITFLOCKTIMEOUTSECS | 60 | Bounded wait for the per-repo am.git-serialize.lock before a git shell-out fails EX_TEMPFAIL (75) |

For the full list of 100+ env vars, see crates/mcp-agent-mail-core/src/config.rs.

For operations guidance and troubleshooting, see docs/OPERATORRUNBOOK.md. For copy-paste operator recipes, see docs/OPERATORCOOKBOOK.md.

Architecture

Cargo workspace with strict dependency layering:

MCP Client / Operator / Browser
   │           │           │
   ├─ stdio ───┤           │
   ├─ HTTP  ───┼───────────┤
   ▼           ▼           ▼
             mcp-agent-mail-server
                     │
        ┌────────────┼────────────┬─────────────┐
        ▼            ▼            ▼             ▼
   37 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

mcpagentmail_rust/
├── Cargo.toml                              # Workspace root (11 member crates)
├── 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/               # 37 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-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 | |------|---------|-------| | ~/.mcpagentmailgitmailbox_repo/ | Legacy archive root (pre-v1) | No longer created; honored if it already exists on disk | | $XDGDATAHOME/mcp-agent-mail/gitmailboxrepo/ | Current archive root (STORAGEROOT default) | ~/.local/share/mcp-agent-mail/gitmailbox_repo/ on most Linux systems | | $XDGCONFIGHOME/mcp-agent-mail/config.env | Canonical env file (installer writes here) | ~/.config/mcp-agent-mail/config.env on most Linux systems | | $XDGCONFIGHOME/mcp-agent-mail/.env | Compatibility env file | Checked when config.env is absent | | ~/.mcpagentmail/.env | Legacy env file | Checked after XDG paths | | ./storage.sqlite3 | Runtime database (DATABASE_URL default) | Relative to working directory, or absolute if configured |

The STORAGEROOT resolution logic: if the legacy path ~/.mcpagentmailgitmailboxrepo/ 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)

$STORAGEROOT/                              # e.g. ~/.local/share/mcp-agent-mail/gitmailbox_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 via frankensearch: lexical tier ships by default in the supported search stack; semantic and hybrid fusion are compiled through the feature = "hybrid" gate, with portable/no-default builds retaining the deterministic lexical path.
• Conformance testing against the Python reference implementation plus Rust-native extensions
• Advisory file reservations with symmetric fnmatch, archive reading, and rename handling
• **`#