Mouchak Mail (Rust)

"Gmail for your coding agents" — High-performance async messaging for AI agent coordination

A production-grade Rust implementation of a mail-like coordination layer for AI coding agents, exposed as both REST API and MCP (Model Context Protocol) server. Enables asynchronous communication between multiple agents working on shared codebases with full audit trails.

44.6x faster than Python — 15,200 req/s vs 341 req/s in original implementation.

Ported from: mcp_agent_mail (Python)

Why This Exists

Modern projects often run multiple coding agents simultaneously (backend, frontend, scripts, infra). Without coordination, agents:

Overwrite each other's edits or panic on unexpected diffs
Miss critical context from parallel workstreams
Require humans to "liaison" messages across tools

Mouchak Mail provides:

Feature	Description
Agent Identity	Memorable adjective+noun names (BlueMountain, GreenCastle)
Messaging	GitHub-Flavored Markdown messages with threading, To/CC/BCC
File Reservations	Advisory locks to prevent edit conflicts (pathspec support)
Contact Management	Explicit approval for cross-project messaging
Searchable Archives	FTS5 full-text search across message bodies
Git-Backed Audit Trail	All messages persisted for human review
Build Slot Management	Exclusive build resource locks
Macro System	Reusable workflow definitions
Product Aggregation	Cross-project inbox for related repositories

Architecture Overview

System Layers

flowchart TB
    subgraph Clients["Client Layer"]
        MCP[/"MCP Clients<br/>(Claude, Cline, VS Code)"/]
        REST[/"REST Clients<br/>(curl, Postman, Apps)"/]
        WebUI[/"Web UI<br/>(SvelteKit + TypeScript)"/]
        CLI[/"CLI<br/>(mouchak-mail-cli)"/]
    end

    subgraph Transport["Transport Layer"]
        STDIO["MCP STDIO<br/>(mouchak-mail-stdio)"]
        SSE["MCP SSE<br/>(rmcp)"]
        HTTP["REST API<br/>(Axum 0.8)"]
    end

    subgraph App["Application Layer (mouchak-mail-server)"]
        MW["Middleware Stack"]
        Handlers["Route Handlers"]
        Tools["MCP Tool Router<br/>(45+ tools)"]
        Embed["Embedded Assets<br/>(rust-embed)"]
    end

    subgraph Business["Business Layer (mouchak-mail-core)"]
        BMC["Backend Model Controllers"]
        MM["ModelManager"]
        Types["Strong Newtypes<br/>(ProjectId, AgentId)"]
        Val["Validation Layer"]
    end

    subgraph Data["Data Layer"]
        SQLite[("SQLite<br/>(libsql + FTS5)")]
        Git[("Git Archive<br/>(git2)")]
    end

    MCP --> STDIO
    MCP --> SSE
    REST --> HTTP
    WebUI --> HTTP
    CLI --> HTTP

    STDIO --> Tools
    SSE --> Tools
    HTTP --> MW --> Handlers
    Embed --> Handlers

    Handlers --> BMC
    Tools --> BMC

    BMC --> MM
    MM --> Types
    Types --> Val
    Val --> SQLite
    Val --> Git

Middleware Stack

flowchart LR
    subgraph Request["Incoming Request"]
        REQ[HTTP Request]
    end

    subgraph Middleware["Middleware Chain"]
        TRACE["TraceLayer<br/>(tower-http)"]
        RATE["Rate Limiter<br/>(governor)"]
        AUTH["Authentication<br/>(Bearer/JWT)"]
        CORS["CORS Handler"]
    end

    subgraph Handler["Route Handler"]
        AXUM["Axum Router"]
        STATE["State Extraction"]
        BODY["JSON Deserialization"]
    end

    REQ --> TRACE --> RATE --> AUTH --> CORS --> AXUM --> STATE --> BODY

Backend Model Controller (BMC) Pattern

The BMC pattern separates concerns for each entity with stateless controllers and strong newtypes:

┌─────────────────────────────────────────────────────────────────┐
│                    Strong Newtypes (mouchak-mail-core/types.rs)           │
├─────────────────────────────────────────────────────────────────┤
│  ProjectId(i64)    │ Compile-time safe project ID               │
│  AgentId(i64)      │ Compile-time safe agent ID                 │
│  MessageId(i64)    │ Compile-time safe message ID               │
│  ProjectSlug(String) │ URL-safe project identifier              │
│  AgentName(String) │ Agent name identifier                      │
├─────────────────────────────────────────────────────────────────┤
│                    Data Structures                               │
├─────────────────────────────────────────────────────────────────┤
│  Agent              │  AgentForCreate    │  AgentForUpdate       │
│  ├─ id: AgentId     │  ├─ name           │  ├─ program          │
│  ├─ name            │  ├─ project_id     │  └─ model            │
│  ├─ project_id      │  ├─ program        │                       │
│  └─ created_at      │  └─ model          │                       │
├─────────────────────────────────────────────────────────────────┤
│                    BMC Controller (Stateless)                    │
├─────────────────────────────────────────────────────────────────┤
│  AgentBmc::create(ctx, mm, data) -> Result<AgentId>             │
│  AgentBmc::get(ctx, mm, id: AgentId) -> Result<Agent>           │
│  AgentBmc::get_by_name(ctx, mm, ProjectId, name) -> Result<Agent> │
│  AgentBmc::list_for_project(ctx, mm, ProjectId) -> Result<Vec<Agent>> │
│  AgentBmc::update(ctx, mm, AgentId, data) -> Result<()>         │
└─────────────────────────────────────────────────────────────────┘

Dual Persistence Model

All data is stored in both systems for query performance and audit trail:

flowchart LR
    subgraph Write["Write Path"]
        BMC[BMC Layer]
    end

    subgraph Primary["Primary Storage"]
        DB[("SQLite (libsql)<br/>━━━━━━━━━━━━━━<br/>• Fast queries<br/>• FTS5 search<br/>• Transactions")]
    end

    subgraph Audit["Audit Trail"]
        GIT[("Git Archive (git2)<br/>━━━━━━━━━━━━━━<br/>• Human-readable<br/>• Version history<br/>• Markdown files")]
    end

    BMC -->|"sync"| DB
    BMC -->|"async"| GIT

Git Archive Structure:

data/archive/projects/{slug}/
├── agents/{name}/
│   ├── profile.json
│   ├── inbox/YYYY/MM/{message}.md
│   └── outbox/YYYY/MM/{message}.md
├── messages/YYYY/MM/{timestamp}__{subject}__{id}.md
└── threads/{thread_id}/
    └── {message_id}.md

Frontend Architecture (SvelteKit)

flowchart TB
    subgraph UI["SvelteKit Application"]
        Routes["Routes Layer"]
        Components["Component Library"]
        State["State Management"]
    end

    subgraph Routes
        Dashboard["/"]
        Inbox["/inbox"]
        Projects["/projects"]
        Agents["/agents"]
        Mail["/mail"]
        Thread["/thread/[id]"]
    end

    subgraph Components
        UI_Lib["shadcn/ui Components<br/>(bits-ui headless)"]
        Layout["Layout Components<br/>(Sidebar, Header)"]
        Magic["Magic Components<br/>(ShimmerButton, effects)"]
        Skeletons["Loading Skeletons"]
    end

    subgraph State
        Stores["Svelte Stores"]
        API["API Client<br/>(/api proxy)"]
    end

    Routes --> Components
    Components --> State
    API -->|"fetch"| Backend["Rust Backend<br/>(:9765)"]

UI Component Categories:

Category	Components
Primitives	Button, Card, Input, Badge, Checkbox, Tooltip
Layout	Sidebar, Sheet, Tabs, Pagination, Resizable
Data	Table, Command Palette, Filter Combobox
Feedback	Skeleton, Alert, Progress, Status Indicator
Effects	ShimmerButton, Spotlight, Theme Toggle

Agent Communication Flow

Typical Multi-Agent Workflow

sequenceDiagram
    participant H as Human Overseer
    participant A as Agent BlueMountain<br/>(Backend)
    participant S as MCP Server
    participant B as Agent GreenCastle<br/>(Frontend)

    Note over H,B: Phase 1: Project Setup

    A->>S: register_agent(project, "BlueMountain", "claude", "opus")
    S-->>A: {id: 1, name: "BlueMountain", capabilities: [...]}

    B->>S: register_agent(project, "GreenCastle", "claude", "sonnet")
    S-->>B: {id: 2, name: "GreenCastle", capabilities: [...]}

    Note over H,B: Phase 2: File Coordination

    A->>S: reserve_file_paths(["src/api/**", "src/models/**"])
    S-->>A: {reserved: true, expires_at: "..."}

    B->>S: reserve_file_paths(["src/components/**"])
    S-->>B: {reserved: true, expires_at: "..."}

    Note over H,B: Phase 3: Work & Communication

    A->>S: send_message(to: "GreenCastle", subject: "API Schema Ready")
    S->>B: (message delivered to inbox)

    B->>S: check_inbox()
    S-->>B: [{from: "BlueMountain", subject: "API Schema Ready"}]

    B->>S: reply_message(thread_id, "Starting UI integration")
    S->>A: (reply delivered)

    Note over H,B: Phase 4: Human Oversight

    H->>S: overseer_send(to: "all", "Please add logging")
    S->>A: (overseer message)
    S->>B: (overseer message)

    A->>S: acknowledge_message(msg_id)
    B->>S: acknowledge_message(msg_id)

    Note over H,B: Phase 5: Cleanup

    A->>S: release_file_paths(["src/api/**", "src/models/**"])
    B->>S: release_file_paths(["src/components/**"])

Message Threading

flowchart TB
    subgraph Thread["Thread: RFC-Authentication"]
        M1["Message 1<br/>━━━━━━━━━━━━━━<br/>From: BlueMountain<br/>Subject: Proposing JWT auth<br/>Priority: high"]
        M2["Message 2<br/>━━━━━━━━━━━━━━<br/>From: GreenCastle<br/>Subject: Re: Proposing JWT auth<br/>Status: read"]
        M3["Message 3<br/>━━━━━━━━━━━━━━<br/>From: RedForest<br/>Subject: Re: Proposing JWT auth<br/>Status: unread"]
    end

    M1 --> M2
    M2 --> M3

File Reservation Conflict Detection

flowchart TD
    A["Agent A: reserve 'src/**/*.ts'"]
    B["Agent B: reserve 'src/api/auth.ts'"]

    A --> Check{Pathspec<br/>Conflict?}
    B --> Check

    Check -->|Yes| Reject["❌ Conflict!<br/>Agent A owns 'src/**/*.ts'"]
    Check -->|No| Grant["✓ Reserved"]

Build Slot Coordination

stateDiagram-v2
    [*] --> Available: slot_type=build

    Available --> Acquired: acquire_build_slot()
    Acquired --> Renewed: renew_build_slot()
    Renewed --> Acquired
    Acquired --> Available: release_build_slot()
    Acquired --> Expired: TTL exceeded
    Expired --> Available: auto-release

Quick Start

Prerequisites

Rust 1.85+ (Edition 2024)
Bun 1.0+ (for SvelteKit frontend)

# Install Bun (macOS/Linux)
curl -fsSL https://bun.sh/install | bash

# Optional: Install cargo-deny for dependency auditing
cargo install cargo-deny

Development Setup

# Clone the repository
git clone https://github.com/Avyukth/mouchak-mail
cd mouchak-mail

# Build all Rust components
cargo build --workspace

# Install frontend dependencies
cd crates/services/web-ui && bun install && cd ../../..

# Run development servers
make dev-backend    # Terminal 1: API on :9765
make dev-frontend   # Terminal 2: SvelteKit with HMR on :5173

Development servers:

API Server: http://localhost:9765
Web UI: http://localhost:5173 (SvelteKit with HMR, proxies to API)

Production Build

# Build unified binary with embedded UI
make build-sidecar

# Run production server (embedded SvelteKit UI)
./target/release/mouchak-mail serve http --port 8765

# Or install globally as 'am'
make install-am-full
am serve http --port 8765

Unified CLI

# Install globally
cargo install --path crates/services/mouchak-mail

# Server modes
mouchak-mail serve http              # REST API server
mouchak-mail serve mcp               # MCP stdio server
mouchak-mail serve mcp --transport sse --port 3000  # SSE server

# Utilities
mouchak-mail tools                   # List MCP tools
mouchak-mail schema                  # Export JSON schema

Claude Desktop Integration

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mouchak-mail": {
      "command": "/path/to/mouchak-mail",
      "args": ["serve", "mcp", "--transport", "stdio"]
    }
  }
}

Project Structure

mouchak-mail/
├── crates/
│   ├── libs/
│   │   ├── mouchak-mail-core/             # Domain logic, BMC pattern, storage
│   │   │   ├── src/model/        # 15+ entities (Agent, Message, Project, etc.)
│   │   │   ├── src/store/        # Database (libsql) + Git (git2) storage
│   │   │   ├── src/types.rs      # Strong newtypes (ProjectId, AgentId, etc.)
│   │   │   └── src/utils/        # Validation, pathspec matching
│   │   ├── mouchak-mail-common/           # Config, errors, tracing
│   │   ├── mouchak-mail-server/           # Axum REST API, middleware, OpenAPI
│   │   │   ├── src/api.rs        # 70+ REST endpoints
│   │   │   ├── src/auth.rs       # Bearer/JWT authentication
│   │   │   ├── src/ratelimit.rs  # Rate limiting (governor)
│   │   │   └── src/embedded.rs   # rust-embed for SvelteKit assets
│   │   └── mouchak-mail-mcp/              # MCP tool definitions
│   │       ├── src/lib.rs        # MouchakMailService with #[tool_router]
│   │       ├── src/tools/        # Tool modules (45+ tools)
│   │       └── src/params.rs     # Auto-generated schemas (JsonSchema)
│   ├── services/
│   │   ├── mouchak-mail-http/           # REST API server binary
│   │   ├── mouchak-mail-stdio/            # MCP protocol server (stdio + SSE)
│   │   ├── mouchak-mail-cli/              # CLI for testing
│   │   ├── mouchak-mail/       # Unified CLI binary (with embedded UI)
│   │   ├── web-ui/               # SvelteKit frontend (TypeScript)
│   │   │   ├── src/routes/       # SvelteKit routes (inbox, projects, agents)
│   │   │   ├── src/lib/components/  # shadcn/ui-style components
│   │   │   └── static/           # Static assets
│   │   └── web-ui-leptos/        # Legacy Leptos WASM frontend
│   └── tests/
│       └── e2e/                  # Playwright E2E tests
├── migrations/                   # SQLite schema (4 migrations, FTS5)
├── data/                         # Runtime data (SQLite DB, Git archive)
├── deny.toml                     # Dependency policy (licenses, advisories)
└── .clippy.toml                  # Clippy configuration

Tech Stack

Layer	Technology
Backend	Rust 2024, Axum 0.8, Tokio
Database	libsql (SQLite) with FTS5 full-text search
Storage	git2 for audit trail
Protocol	MCP via rmcp SDK (stdio + SSE)
Frontend	SvelteKit 2.0, TypeScript 5.0, TailwindCSS 3.4
Components	shadcn/ui-style (bits-ui), Lucide icons
Build	Vite 6.0, Bun, rust-embed (embedded assets)
Metrics	Prometheus (metrics-exporter-prometheus)
Testing	Playwright (E2E), cargo test (unit/integration)
Quality	cargo-deny, clippy, pmat

API Reference

Health & Monitoring

Endpoint	Method	Description
`/api/health`	GET	Health check with uptime
`/api/ready`	GET	Readiness probe (DB connectivity)
`/api/metrics`	GET	Prometheus metrics

Projects

Endpoint	Method	Description
`/api/project/ensure`	POST	Create or get existing project
`/api/projects`	GET	List all projects
`/api/projects/{slug}/agents`	GET	List agents for project
`/api/project/info`	POST	Get project details

Agent Management

Endpoint	Method	Description
`/api/agent/register`	POST	Register new agent
`/api/agent/whois`	POST	Lookup agent by name
`/api/agent/create_identity`	POST	Create with auto-generated name
`/api/agent/profile`	POST	Get agent profile
`/api/agent/capabilities`	POST	Check/grant capabilities

Messaging

Endpoint	Method	Description
`/api/message/send`	POST	Send message (to/cc/bcc)
`/api/message/reply`	POST	Reply to thread
`/api/message/acknowledge`	POST	Acknowledge receipt
`/api/messages/search`	POST	Full-text search
`/api/inbox`	POST	List inbox messages
`/api/outbox`	POST	List sent messages
`/api/thread/summarize`	POST	Summarize thread

File Reservations

Endpoint	Method	Description
`/api/file_reservations/paths`	POST	Reserve file paths (pathspec)
`/api/file_reservations/list`	POST	List active reservations
`/api/file_reservations/release`	POST	Release reservations
`/api/file_reservations/renew`	POST	Extend TTL

Build Slots

Endpoint	Method	Description
`/api/build_slots/acquire`	POST	Acquire exclusive slot
`/api/build_slots/renew`	POST	Extend TTL
`/api/build_slots/release`	POST	Release slot

Products (Multi-Project)

Endpoint	Method	Description
`/api/product/ensure`	POST	Create or get product
`/api/product/link_project`	POST	Link project to product
`/api/product/inbox`	POST	Cross-project inbox

MCP Protocol

Tool Categories (45+ tools)

Category	Tools	Description
Infrastructure	`health`, `ready`, `metrics`	Server health and monitoring
Project	`ensure_project`, `list_projects`, `get_project_info`	Project lifecycle
Agent	`register_agent`, `whois`, `list_agents`	Agent identity
Messaging	`send_message`, `check_inbox`, `reply_message`, `search_messages`	Core messaging
Threads	`list_threads`, `get_thread`, `summarize_thread`	Conversations
Files	`reserve_file_paths`, `release_file_paths`, `check_paths`	File coordination
Build	`acquire_build_slot`, `release_build_slot`	Build coordination
Products	`ensure_product`, `link_project`, `product_inbox`	Multi-project
Contacts	`add_contact`, `list_contacts`, `block_contact`	Agent routing
Macros	`register_macro`, `invoke_macro`	Workflow automation
Overseer	`overseer_send`, `overseer_inbox`	Human guidance

Request Flow

sequenceDiagram
    participant C as MCP Client
    participant S as STDIO Transport
    participant R as Tool Router
    participant H as ServerHandler
    participant B as BMC Layer
    participant D as Database

    C->>S: JSON-RPC request
    S->>H: list_tools() / call_tool()

    alt list_tools
        H->>R: get_tool_schemas()
        R-->>H: [Tool schemas with descriptions]
    else call_tool
        H->>R: dispatch(tool_name, params)
        R->>B: BMC method call
        B->>D: SQL query
        D-->>B: Result rows
        B-->>R: Domain objects
        R-->>H: JSON response
    end

    H-->>S: JSON-RPC response
    S-->>C: Result / Error

Configuration

Environment Variables

Server:

Variable	Default	Description
`PORT`	8765	API server port
`MOUCHAK_SERVER__HOST`	0.0.0.0	Bind address

Logging:

Variable	Default	Description
`RUST_LOG`	info	Log level (debug, info, warn, error)
`LOG_FORMAT`	pretty	Log format (pretty, json)
`RUN_MODE`	development	Mode (development, production, test)

Database:

Variable	Default	Description
`SQLITE_PATH`	./data/mouchak_mail.db	SQLite file path
`DATABASE_URL`	file:./data/mouchak_mail.db	Database URL

Git Archive:

Variable	Default	Description
`GIT_REPO_PATH`	./data/archive	Archive location
`GIT_ARCHIVE_ENABLED`	false	Enable git archival

Rate Limiting:

Variable	Default	Description
`RATE_LIMIT_ENABLED`	true	Enable rate limiting
`RATE_LIMIT_RPS`	1000	Requests per second
`RATE_LIMIT_BURST`	2000	Burst allowance

MCP Protocol:

Variable	Default	Description
`MOUCHAK_MCP__TRANSPORT`	stdio	Transport (stdio, sse)
`MOUCHAK_MCP__PORT`	3000	SSE port

Development

Commands (make)

# Development (two terminals recommended)
make dev-backend    # API server on :9765
make dev-frontend   # SvelteKit HMR on :5173 (proxies to API)

# Single server with embedded UI
make dev-web        # Build SvelteKit + serve on :8765

# Build
make build-release  # Build Rust release with LTO
make build-sidecar  # Build unified binary with embedded SvelteKit UI
make build-prod     # Full production build (UI + Rust)

# Testing
make test           # Run all integration tests
make test-fast      # Run unit tests only
make lint           # Run clippy lints

# Quality & Security
make audit          # Run cargo audit + cargo deny
make quality-gate   # Run all quality gates (fmt, lint, test, pmat)

Quality Gates

Workspace Lints:

unsafe_code = "deny" — No unsafe code allowed
unused_must_use = "deny" — Enforce error handling

Clippy Configuration:

Cognitive complexity threshold: 30
Max function lines: 200
MSRV: 1.85

Dependency Policy (deny.toml):

License allowlist (MIT, Apache-2.0, BSD, ISC)
Security advisory checks

Performance

Benchmarked against Python reference implementation:

Metric	Rust	Python	Improvement
Requests/sec	15,200	341	44.6x
P99 Latency	2.1ms	89ms	42x
Memory (idle)	12MB	180MB	15x
Startup time	50ms	2.1s	42x

Key Optimizations:

Shared ModelManager across MCP sessions
Connection pooling with libsql
Zero-copy JSON serialization
Async I/O throughout with tokio
LRU repo cache (8 repos) for concurrent agents

Database Schema

SQLite with FTS5 full-text search. 15 tables across 4 migrations:

Table	Description
`projects`	Project registry (slug, human_key)
`agents`	Agent profiles with capabilities
`messages`	Message content with threading
`message_recipients`	To/CC/BCC with read/ack tracking
`messages_fts`	FTS5 index for full-text search
`file_reservations`	Advisory file locks with TTL
`build_slots`	Exclusive build resource locks
`agent_capabilities`	Per-agent capability grants
`products`	Multi-repo coordination
`tool_metrics`	Tool usage tracking

References

Python Original — Source implementation
MCP Protocol — Model Context Protocol specification
Beads Issue Tracker — Task tracking via bd CLI
PMAT Quality Gates — Production maturity analysis

License

MIT License — See LICENSE file for details.

Built with Rust for memory safety, performance, and reliability.

Name		Name	Last commit message	Last commit date
Latest commit History 706 Commits
.beads		.beads
.cargo-husky/hooks		.cargo-husky/hooks
.cargo		.cargo
.githooks		.githooks
.github		.github
benches		benches
crates		crates
deploy		deploy
migrations		migrations
mouchak-brand-assets		mouchak-brand-assets
scripts		scripts
.clippy.toml		.clippy.toml
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pmat-gates.toml		.pmat-gates.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
.release-please-manifest.json		.release-please-manifest.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE.md		LICENSE.md
Makefile		Makefile
README.md		README.md
cliff.toml		cliff.toml
deny.toml		deny.toml
docker-compose.yml		docker-compose.yml
package.json		package.json
pmat.toml		pmat.toml
release-please-config.json		release-please-config.json

Folders and files

Latest commit

History

Repository files navigation

Mouchak Mail (Rust)

Table of Contents

Why This Exists

Architecture Overview

System Layers

Middleware Stack

Backend Model Controller (BMC) Pattern

Dual Persistence Model

Frontend Architecture (SvelteKit)

Agent Communication Flow

Typical Multi-Agent Workflow

Message Threading

File Reservation Conflict Detection

Build Slot Coordination

Quick Start

Prerequisites

Development Setup

Production Build

Unified CLI

Claude Desktop Integration

Project Structure

Tech Stack

API Reference

Health & Monitoring

Projects

Agent Management

Messaging

File Reservations

Build Slots

Products (Multi-Project)

MCP Protocol

Tool Categories (45+ tools)

Request Flow

Configuration

Environment Variables

Development

Commands (make)

Quality Gates

Performance

Database Schema

References

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages