agent-team-mail (atm)

Mail-like messaging for Claude agent teams.

atm is a Rust CLI and library for sending and receiving messages between Claude agents in a team. It provides atomic file I/O operations over the ~/.claude/teams/ directory structure with conflict detection, guaranteed delivery, and schema versioning.

Features

• Simple messaging: Send messages to agents, broadcast to teams, read your inbox
• Atomic operations: Safe concurrent access with platform-specific atomic file swaps
• Conflict detection: Hash-based detection and automatic merge of concurrent writes
• Guaranteed delivery: Outbound spool with retry logic ensures messages aren't lost
• Schema versioning: Forward-compatible with unknown JSON fields preserved on round-trip
• Cross-platform: Works on macOS, Linux, and Windows

Installation

Pre-built Binaries (GitHub Releases)

Download the latest release for your platform from GitHub Releases:

Extract and place atm (and optionally atm-daemon and atm-agent-mcp) somewhere in your $PATH.

Homebrew (macOS/Linux)

brew tap randlee/tap
brew install agent-team-mail

crates.io

# Install the CLI
cargo install agent-team-mail

# Install the daemon (optional)
cargo install agent-team-mail-daemon

# Install the MCP proxy (optional)
cargo install agent-team-mail-mcp

# Install the TUI dashboard (optional)
cargo install agent-team-mail-tui

# Install sc-compose prompt composer CLI (optional)
cargo install sc-compose

Build from Source

git clone https://github.com/randlee/agent-team-mail.git
cd agent-team-mail
cargo install --path crates/atm
# Optionally install the daemon:
cargo install --path crates/atm-daemon
# Optionally install the MCP proxy:
cargo install --path crates/atm-agent-mcp

The atm, atm-daemon, and atm-agent-mcp binaries will be available in your $PATH.

Quick Start

Compose a prompt with sc-compose

# Validate a template (returns exit 2 on validation failure)
sc-compose --root . validate .claude/agents/rust-dev.md.j2

# Render template to stdout
sc-compose --root . --var role=engineer render .claude/agents/rust-dev.md.j2

# Render and derive output path from .j2 suffix (for example template.md.j2 -> template.md)
sc-compose --root . --var role=engineer render .claude/agents/rust-dev.md.j2 --write

sc-compose logging controls:

• SC_COMPOSE_LOG_LEVEL = trace|debug|info|warn|error (default: info)
• SC_COMPOSE_LOG_FORMAT = jsonl|human (default: jsonl)
• SC_COMPOSE_LOG_FILE = explicit log path override

Default log path (when SC_COMPOSE_LOG_FILE is not set):

• Linux/macOS: ${XDG_CONFIG_HOME:-$HOME/.config}/sc-compose/logs/sc-compose.log
• Windows: %APPDATA%/sc-compose/logs/sc-compose.log (fallback via home directory)

Default spool path:

• sibling log-spool directory next to the active log path (for example ${XDG_CONFIG_HOME:-$HOME/.config}/sc-compose/log-spool).

Send a message

# Send to an agent on the default team
atm send agent-name "Hello from the terminal"

# Send to an agent on a specific team
atm send agent-name@team-name "Cross-team message"

# Send with explicit summary
atm send agent-name "Important update" --summary "Deploy notification"

Read your inbox

# Read unread messages (marks them as read)
atm read

# Read all messages without marking as read
atm read --all --no-mark

# Read someone else's inbox
atm read other-agent

Broadcast to a team

# Broadcast to all members of the default team
atm broadcast "Team-wide announcement"

# Broadcast to a specific team
atm broadcast --team backend-ci "CI pipeline updated"

Check team status

# Show overview of default team
atm status

# List all teams
atm teams

# List members of a team
atm members backend-ci

Commands

Run atm <command> --help for detailed usage of each command.

Configuration

atm resolves configuration from multiple sources (highest priority first):

1. Command-line flags (--team, --identity)
2. Environment variables (ATM_TEAM, ATM_IDENTITY, ATM_NO_COLOR)
3. Repo-local config (.atm.toml in current directory or git root)
4. Global config (~/.config/atm/config.toml)
5. Defaults

Example .atm.toml

[core]
default_team = "backend-ci-team"
identity = "human"

[display]
format = "text"  # text | json
color = true
timestamps = "relative"  # relative | absolute | iso8601

Environment Variables

• ATM_TEAM — Default team name
• ATM_IDENTITY — Sender identity for messages
• ATM_CONFIG — Path to config file override
• ATM_NO_COLOR — Disable colored output
• ATM_HOME — Override home directory (mainly for testing)

Architecture

The project is organized as a Cargo workspace with three crates:

agent-team-mail/
├── crates/
│   ├── atm-core/       # Shared library (schema types, atomic I/O, config)
│   ├── atm/            # CLI binary (commands, output formatting)
│   ├── atm-daemon/     # Daemon with plugin system
│   └── atm-agent-mcp/  # MCP proxy for agent tool access

atm-core

Shared library providing:

• Schema types with versioning (TeamConfig, InboxMessage, TaskItem, SettingsJson)
• Atomic file I/O with platform-specific swaps (renamex_np on macOS, renameat2 on Linux)
• Conflict detection via content hashing (BLAKE3)
• File locking (flock) for coordination between atm processes
• Outbound spool for guaranteed delivery with retry logic
• Config resolution from multiple sources

atm

CLI binary with subcommands for:

• Messaging (send, broadcast, read, inbox)
• Discovery (teams, members, status)
• Configuration (config)

atm-daemon (post-MVP)

Always-on daemon with plugin system for:

• Issues plugin: Bridge GitHub/Azure DevOps issues to agent inboxes
• CI Monitor plugin: Watch CI workflows and notify agents of failures
• Bridge plugin: Enable cross-machine agent teams
• Human Chat plugin: Connect chat apps (Slack, Discord) to agent teams

Development

See docs/project-plan.md for the development workflow and sprint plan.

Running Tests

# Run all tests
cargo test --workspace

# Run clippy
cargo clippy --workspace -- -D warnings

# Generate documentation
cargo doc --no-deps --workspace --open

Cross-Platform Testing

The CI runs tests on macOS, Linux, and Windows. See docs/cross-platform-guidelines.md for platform-specific patterns (especially Windows home directory handling).

Documentation

• docs/requirements.md — System requirements and architecture
• docs/project-plan.md — Sprint plan and development workflow
• docs/agent-team-api.md — Claude agent team file-based API reference
• docs/cross-platform-guidelines.md — Windows CI compliance patterns

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! See docs/project-plan.md for the development workflow.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.