Agent Mail + Beads = Coordinated AI Coding Agents – How Git Worktrees Make It Practical

Author’s note:

Question: What is Agent Mail? How does Beads package help?

Context: Context:

More like 40-50 at once with no issues. And a mixture of CC, Codex, and Gemini-cli.

And I do to all with Agent Mail and beads and bv and my prompts and workflows I’ve shared here.

Worktrees suck and just kick the can down the road. Advisory file reservations and messaging ftw.
— Jeffrey Emanuel (@doodlestein) January 11, 2026

Also https://x.com/bholmesdev/status/2010189144123998669?s=46

Why aren’t worktrees ideal? What are git worktrees and why do so many agent workflows use them?

Executive Summary

As AI coding agents move from experimental scripts to production-grade engineers, coordination has become the primary bottleneck. When multiple agents work on the same codebase simultaneously, they risk overwriting each other’s changes and losing context.

Agent Mail and Beads have emerged as the standard stack for solving this problem. Agent Mail provides a “Gmail-like” coordination layer that allows agents to communicate intent and reserve files before editing ¹ ². Beads complements this by providing a persistent, Git-backed issue graph that gives agents long-term memory and task tracking capabilities ³ ⁴.

To make this practical, developers are increasingly adopting Git worktrees. Worktrees allow multiple agents to operate on different branches of the same repository simultaneously without the overhead of full cloning ⁵ ⁶. However, this approach introduces new complexity, particularly around file system overhead and branch management ⁷.

This report details how these three technologies—Agent Mail, Beads, and Git worktrees—combine to create a robust environment for multi-agent software development.

What Is Agent Mail?

Agent Mail is an open-source coordination layer designed specifically for AI coding agents. It functions as an HTTP-only FastMCP server that provides agents with a structured way to communicate, register identities, and avoid conflicts ¹ ².

Purpose & Design Goals

The primary goal of Agent Mail is to act as “Gmail for your coding agents” ¹. In a multi-agent environment, agents often lack a shared context. Without coordination, they may:

Overwrite each other’s edits.
Miss critical context from parallel workstreams.
Require human intervention to pass messages between tools ¹.

Agent Mail solves this by providing:

Identity Management: Agents register memorable “adjective+noun” names (e.g., GreenCastle) to establish persistent identities ¹.
Async Messaging: An inbox/outbox system backed by Git for human-auditable history and SQLite for fast indexing ¹.
Conflict Avoidance: A file reservation system that allows agents to “lease” files before editing them ².

Core API Quick Reference

Agent Mail exposes its functionality through a set of MCP tools. Key tools include:

Tool Name	Signature	Description
`register_agent`	`register_agent(project_key, program, model, name?,...)`	Creates or updates a named identity and persists the profile to Git ¹.
`send_message`	`send_message(project_key, sender, to, subject, body,...)`	Writes a canonical message to the `messages/` directory and updates recipient inboxes ¹.
`fetch_inbox`	`fetch_inbox(project_key, agent_name, since_ts?,...)`	Retrieves recent messages for an agent, preserving thread IDs ¹.
`file_reservation_paths`	`file_reservation_paths(project_key, agent_name, paths,...)`	Records an advisory lease on specific files to signal intent to other agents ¹.

File-Reservation “Leases”

One of Agent Mail’s most critical features is its file reservation system. Agents can request an “exclusive” lease on a file or directory for a specific Time-To-Live (TTL) ¹.

Advisory by Default: The system records the lease in a database and writes a JSON artifact to Git. If another agent tries to reserve the same file, the system reports a conflict ¹.
Optional Enforcement: For stricter control, teams can install a pre-commit hook (install_precommit_guard) that blocks commits if they conflict with an active exclusive reservation held by another agent ¹ ².

Web UI & Observability

While agents interact via API, humans need visibility. Agent Mail includes a server-rendered Web UI that allows developers to:

Browse project inboxes and read agent conversations.
View active file reservations and their expiration status.
Perform full-text searches across all messages using SQLite’s FTS5 engine ¹.

The Beads Package – A Memory Upgrade for Agents

While Agent Mail handles communication, Beads handles memory and planning. It is a distributed, Git-backed issue tracker designed to give agents a persistent graph of tasks ³.

Architecture Overview

Beads replaces fragile markdown plans with a structured database.

Git as Database: Issues are stored as JSONL files in a .beads/ directory within the repository. This means issues are versioned, branched, and merged exactly like code ³ ⁴.
Local Caching: To ensure speed, Beads maintains an invisible SQLite cache that allows for sub-second queries, while a background daemon handles synchronization ³.

Issue Graph & Dependency Links

Beads structures work as a graph rather than a flat list. Issues can have parent/child relationships (epics) and blocking dependencies ⁴. This allows agents to:

Break down large tasks into “beads on a string.”
Identify “auto-ready” tasks that are unblocked and ready for execution ³.
Maintain context over long horizons without getting lost in a massive plan ³.

Conflict-Free IDs & Merging

A major challenge in distributed agent work is ID collision. If two agents on different branches create “Issue #5,” merging becomes a nightmare.

Zero-Conflict IDs: Beads generates hash-based IDs (e.g., bd-a1b2) instead of sequential numbers. This ensures that issues created on separate branches never collide during a merge ³.
Intelligent Merging: Because the data is just JSONL lines in Git, standard Git merge strategies (often aided by AI) can resolve updates from multiple agents seamlessly ⁴.

Compaction & Memory Decay

To prevent the agent’s context window from overflowing with history, Beads includes a “compaction” feature. It semantically summarizes old, closed tasks, effectively implementing a form of “memory decay” that keeps the active context lightweight ³.

Git Worktrees – Mechanics & Why Agents Love Them

To allow multiple agents to work on the same repository effectively, developers use Git worktrees.

Basic Commands

A standard Git repository has one working directory. git worktree allows you to check out multiple branches at once in separate directories, all linked to the same repository history ⁵ ⁸.

Add a worktree: git worktree add <path> <branch> creates a new directory with the specified branch checked out ⁸.
List worktrees: git worktree list shows all active worktrees and their paths ⁵.
Remove a worktree: git worktree remove <path> deletes the worktree directory and updates Git’s internal state ⁸.
Prune: git worktree prune cleans up stale administrative files if a worktree was deleted manually ⁸.

Benefits for Parallel Agents

Worktrees are ideal for agent workflows because:

Isolation: Each agent gets its own directory. Agent A can run tests on feature-A while Agent B edits feature-B without their file systems clashing ⁶.
Efficiency: Unlike cloning the repo multiple times, worktrees share the .git object database. This saves disk space and means an object fetched in one worktree is instantly available in others ⁷.
Context Switching: Agents don’t need to git stash and git checkout. They simply operate in their assigned directory ⁵.

Limitations & Gotchas

Despite their utility, worktrees have constraints that can trip up agent workflows:

Same-Branch Rule: You cannot check out the same branch in two different worktrees simultaneously. Git enforces this to prevent state corruption ⁷ ⁹.
Folder Overhead: Each worktree is a full directory of files. For massive monorepos, creating 50 worktrees can consume significant disk space and hit OS file handle limits ⁷.
Tooling Compatibility: Some tools expect the .git item to be a directory, but in a worktree, .git is a file pointing to the main repository. This can break older scripts or tools ⁷.

Putting It All Together – A Full-Stack Coordination Pattern

By combining these three technologies, you can create a “Beads Village” where multiple agents collaborate autonomously ¹⁰.

Repository Layout

A typical setup involves a main repository and transient worktrees for agents.

/my-project
 /.git # Shared object database
 /.beads # Shared issue graph (synced via Git)
 /mail # Agent Mail storage (synced via Git)
 /worktrees
 /agent-frontend # Worktree for frontend agent
 /agent-backend # Worktree for backend agent

Agent Bootstrap Script

When an agent starts, it needs to set up its environment. A bootstrap script might look like this:

# 1. Create a unique branch and worktree for the agent
AGENT_ID="agent-$(date +%s)"
git branch $AGENT_ID main
git worktree add./worktrees/$AGENT_ID $AGENT_ID

# 2. Register with Agent Mail
# (Pseudo-code for calling MCP tool)
call_mcp_tool "register_agent" --name "BlueBuilder" --project "my-project"

# 3. Reserve critical files
call_mcp_tool "file_reservation_paths" \
 --agent "BlueBuilder" \
 --paths '["src/frontend/*"]' \
 --exclusive true

# 4. Pull tasks from Beads
bd issue list --status ready

CI Pipeline Integration

In a CI environment, this stack allows for dynamic parallelism.

Trigger: A new issue in Beads is marked ready.
Spin-up: CI allocates a new worktree for an agent.
Execution: The agent reads the issue, reserves files via Agent Mail, implements the fix, and pushes the branch.
Merge: Because Beads IDs are hash-based, the agent’s update to the issue graph merges cleanly with other agents’ updates ³.

Comparison of Coordination Strategies

Strategy	Persistence	Conflict Handling	Scaling (Agents)	Setup Complexity
Agent Mail + Beads + Worktrees	Git + SQLite (Local & Distributed)	Hash-ID + Advisory Leases (Enforced via hook)	High (Native Git branching, unlimited per-branch agents)	Medium (Requires MCP wrapper & pre-commit hooks)
Plain File Locking	Filesystem only	OS-level lock files (Prone to stale locks)	Low (Hard to coordinate >10 agents)	Low (No extra deps)
External MQ (Kafka/RabbitMQ)	Remote Broker	Exactly-once semantics (Requires config)	Very High (High throughput)	High (Requires infra & client libs)

Best Practices & Common Pitfalls

Enforce Reservations: Do not rely solely on advisory leases. Enable FILE_RESERVATIONS_ENFORCEMENT_ENABLED=true and install the pre-commit guard to prevent “silent” conflicts where an agent ignores a reservation ¹ ².
Prune Aggressively: Worktrees can accumulate rapidly. Automate git worktree prune in your CI scripts to remove stale entries and free up disk space ⁸.
Monitor SQLite Latency: Beads relies on a local SQLite cache. Ensure your agents have fast local disk access; running this on high-latency network mounts can degrade performance ³.
Unique Branches: Always create a unique branch for every new worktree. Attempting to reuse a branch name will cause the git worktree add command to fail ⁷.

Bottom Line

The combination of Agent Mail, Beads, and Git worktrees creates a self-contained, audit-friendly ecosystem for AI development. Agent Mail prevents agents from stepping on each other’s toes ¹, Beads ensures they remember what they are doing ³, and Git worktrees provide the physical isolation needed to execute tasks in parallel ⁶. For teams building multi-agent systems, this stack transforms chaos into a coordinated engineering process.