Agent Mail Reference Library

Spec Explorer

Browse implementation notes, protocol references, and operational docs that support the MCP Agent Mail architecture.

Tool Clusters

34 tools across 9 clusters

  • Infrastructure: Bootstrap project context, health checks, and server lifecycle visibility.
  • Identity: Create or update persistent agent identities and profile metadata.
  • Messaging: Coordinate work asynchronously with durable, threaded, auditable messages.
  • Contacts: Control who can message whom across teams and projects.
  • File Reservations: Advertise file ownership intent and avoid stepping on parallel edits.
  • Search: Recover context rapidly from message history and thread archives.
  • Macros: Collapse common multi-step workflows into one predictable tool call.
  • Product Bus: Link multiple repos under one product-level coordination surface.
  • Build Slots: Throttle expensive builds/tests to prevent CI or machine contention.

MCP Resources

Resource URI model

  • resource://inbox/{agent} — Read latest inbox messages without issuing tool calls.
  • resource://thread/{thread_id} — Retrieve thread history in one structured snapshot.
  • resource://agents/{project_key} — Enumerate known agents and their contactable identities.
  • resource://file_reservations/{project_key} — Inspect active lease ownership and expiry windows.
  • resource://contacts/{agent} — Show contact graph and approval state.
  • resource://metrics/{project_key} — Expose throughput/error/latency telemetry snapshots.
  • resource://health — Report service readiness and degraded-mode signals.

TUI Screens

15-screen operations map

  • Dashboard: Is the system healthy and active right now?
  • Inbox Browser: What requires my immediate response?
  • Thread Explorer: How did this decision evolve over time?
  • Agent Roster: Who is online and what are they doing?
  • Reservation Manager: Where are file ownership conflicts emerging?
  • Unified Search: Where is the prior context for this topic?
  • Contact Graph: Can this agent message that agent right now?
  • Macro Inspector: Which high-level workflows are available and safe?
  • Build Slots: Are build leases saturating shared infrastructure?
  • Product Bus: How are projects linked under shared products?
  • Audit Timeline: What happened and when?
  • System Health: Which subsystem is degraded?
  • Human Overseer: How can an operator redirect execution quickly?
  • Tool Metrics: Which tools are hot or failing?
  • Theme + Session Status: Is this session readable and context-aligned?

Robot Mode

Command tracks

  • Situational Awareness: Get fast status before taking action.

    am robot status --format toon

  • Message Triage: Prioritize and acknowledge inbound coordination tasks.

    am robot inbox --format json --agent GreenCastle

  • History Retrieval: Recover past decisions before proposing changes.

    am robot search --format json "auth refactor"

  • Edit Safety: Inspect ownership and avoid reservation collisions.

    am robot reservations --format json

  • Operator Reporting: Produce machine-readable snapshots for automation and dashboards.

    am robot status --format json > status.snapshot.json

Visualization Execution Plan

Must / Should / Stretch backlog

Must

  • 1. Macro Orchestration Flow (Start Session / Prepare Thread / Reservation Cycle)

    Wave 1: Core Loop | EV 5/5 | IC 2/5 | TR 2/5

    home / getting-started / showcase

  • 2. Message Lifecycle + Thread State

    Wave 1: Core Loop | EV 5/5 | IC 3/5 | TR 3/5

    home / showcase

  • 3. File Reservation + Guardrail Conflict Resolution

    Wave 2: Guardrails | EV 5/5 | IC 3/5 | TR 3/5

    home / showcase / architecture

  • 4. Inbox Workload Lanes + Urgent Triage

    Wave 2: Guardrails | EV 4/5 | IC 3/5 | TR 3/5

    home / showcase

  • 5. Search V3 Hybrid Pipeline

    Wave 3: Scale + Observability | EV 5/5 | IC 4/5 | TR 4/5

    showcase / architecture

  • 6. Product Bus Cross-Project Topology

    Wave 3: Scale + Observability | EV 4/5 | IC 3/5 | TR 3/5

    home / architecture

Should

  • 7. Contact Policy + Handshake Graph

    Wave 2: Guardrails | EV 4/5 | IC 3/5 | TR 3/5

    architecture / showcase

  • 8. Acknowledgment Overdue Risk Monitor

    Wave 2: Guardrails | EV 4/5 | IC 2/5 | TR 2/5

    showcase / architecture

  • 9. Build Slot Contention + Lease Renewal

    Wave 3: Scale + Observability | EV 3/5 | IC 2/5 | TR 2/5

    architecture / showcase

  • 10. MCP Resource URI Map

    Wave 3: Scale + Observability | EV 3/5 | IC 1/5 | TR 1/5

    architecture / showcase

  • 11. 15-Screen TUI Atlas

    Wave 3: Scale + Observability | EV 3/5 | IC 2/5 | TR 2/5

    showcase / architecture

Stretch

  • 12. SQLite + Git Dual-Write Audit Path

    Wave 4: Advanced Internals | EV 4/5 | IC 4/5 | TR 4/5

    architecture

  • 13. Stress Gauntlet Scenario Outcomes

    Wave 4: Advanced Internals | EV 3/5 | IC 2/5 | TR 3/5

    home / showcase