Skip to content

README.md

Latest commit

 

History

History
151 lines (105 loc) · 3.89 KB

README.md

File metadata and controls

151 lines (105 loc) · 3.89 KB
Raw

mailz

Agent coordination via mail-style messaging, with CLI, TUI, MCP, and HTTP API interfaces.

Heavily inspired by mcp_agent_mail by Jeffrey Emanuel.

Overview

mailz keeps lightweight, auditable coordination data in a local SQLite database. Agents can send messages, request acknowledgements, and reserve files to avoid conflicts. Operators can manage projects and agents from a CLI or TUI, and integrate via HTTP API or MCP.

Install

Build from source:

cargo build --release

Quick Start

Initialize config and register an agent:

cargo run -p mailz-cli -- init
cargo run -p mailz-cli -- project create /path/to/repo --name repo
cargo run -p mailz-cli -- agent register repo --name "AgentA" --program "cli" --model "gpt"

Send a message and check inbox:

cargo run -p mailz-cli -- send repo --from AgentA --to AgentB --subject "Heads up" --body "Working on parser."
cargo run -p mailz-cli -- inbox repo --agent AgentB

Start the TUI:

cargo run -p mailz-tui

Start the API server:

cargo run -p mailz-api -- --port 3000

Start the MCP server:

cargo run -p mailz-mcp

CLI Examples

Register agents and send messages:

cargo run -p mailz-cli -- agent register repo --name "AgentB" --program "cursor" --model "gpt"
cargo run -p mailz-cli -- send repo --from AgentA --to AgentB --subject "Review" --body "Please review parser changes."

Reserve files for coordinated edits:

cargo run -p mailz-cli -- reserve repo --agent AgentA src/parser.rs --ttl 1200 --reason "Refactor"
cargo run -p mailz-cli -- reservations repo

Watch for new messages:

cargo run -p mailz-cli -- watch
cargo run -p mailz-cli -- daemon start
cargo run -p mailz-cli -- daemon status
cargo run -p mailz-cli -- daemon stop

TUI Basics

  • j/k or arrows to navigate, c to compose, t for reservations, g for directory.
  • / to search inbox, r to toggle read, a to acknowledge.
  • Directory view shows projects (Tab to switch) and agents with unread/total counts.

API Examples

Admin key is required for management endpoints. Set api.admin_key in config or read the auto generated key from the state directory.

Create a project and agent:

curl -H "X-API-Key: $MAILZ_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/path/to/repo","name":"repo"}' \
  http://localhost:3000/projects

curl -H "X-API-Key: $MAILZ_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"AgentA","program":"api","model":"gpt"}' \
  http://localhost:3000/projects/1/agents

Issue an agent key and use it to read inbox:

curl -H "X-API-Key: $MAILZ_ADMIN_KEY" http://localhost:3000/agents/1/keys

curl -H "X-API-Key: $MAILZ_AGENT_KEY" http://localhost:3000/agents/1/inbox

Connect to WebSocket updates (requires websocat):

websocat -H "X-API-Key: $MAILZ_AGENT_KEY" \
  ws://localhost:3000/ws/1

MCP Examples

Run the MCP server and call tools such as:

  • ensure_project
  • register_agent
  • send_message
  • fetch_inbox
  • reserve_files

Configuration Reference

Default config path: $XDG_CONFIG_HOME/mailz/config.toml

Key sections (see examples/config.toml):

  • logging.level, logging.file
  • runtime.parallelism, runtime.timeout, runtime.fail_fast
  • paths.data_dir, paths.state_dir
  • maintenance.gc_interval_seconds, maintenance.message_retention_days
  • api.admin_key, api.rate_limit_per_minute
  • tui.poll_interval_seconds
  • watch.poll_interval_seconds

Agent Coordination Patterns

  • Create one project per repo/workspace and register each agent/tool once.
  • Use reserve before editing shared files; release when done.
  • Mark read/acknowledge important messages to keep the inbox clean.
  • Use threads (thread_id) to group related discussions.
  • Keep agent names consistent across CLI, API, and MCP for clear audit trails.