MCP Agent Mail (Rust)
<div align="center">
<img src="https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/HEAD/docs/assets/am_illustration.webp" alt="MCP 에이전트 메일 - AI 코딩 에이전트를 위한 메일과 같은 조정 계층">
</div>
<div align="center">
License: MIT+Rider
</div>
"코딩 에이전트에게는 마치 Gmail 같아요!"
AI 코딩 에이전트를 위한 메일과 같은 조정 계층으로, 45개의 도구와 25개의 리소스를 가진 MCP 서버로 노출되며, Git 기반 아카이브, SQLite 인덱싱, 대화형 16개 화면 TUI(Text User Interface), 서버 렌더링 웹 UI, 그리고 에이전트 우선 로봇 CLI를 제공합니다. 원래 Python 프로젝트 (1,700+ stars)의 Rust 재작성 버전입니다.
지원되는 에이전트: Claude Code, Codex CLI, Gemini CLI, Oh My Pi (OMP), GitHub Copilot CLI, 그리고 모든 MCP 호환 클라이언트.
23분짜리 워크스루(walkthrough)를 시청하여 7개의 AI 코딩 에이전트가 이틀에 걸쳐 개발 계획을 구현하는 동안 서로에게 1,000개 이상의 메시지를 보내는 것을 확인해 보세요.
<div align="center">
<h3 id="quick-install">빠른 설치</h3>
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.sh?$(date +%s)" | bash
<p><em class="text-gray-600">Linux 및 macOS(x86_64 및 aarch64)에서 작동합니다. 플랫폼을 자동 감지하고, 적절한 바이너리를 다운로드하며, 감지된 코딩 에이전트를 HTTP MCP에 대해 구성합니다.</em></p>
<p><em class="text-gray-600">릴리스를 확인하려면 <code class="bg-gray-100 p-1 rounded">minisign</code>이 <code class="bg-gray-100 p-1 rounded">PATH</code>에 필요하며 (최소 Linux 이미지의 경우 <code class="bg-gray-100 p-1 rounded">xz</code>가 필요합니다); <a href="#one-liner-recommended">원라인(One-Liner)</a>을 참조하세요.</em></p>
</div>
목차
다음은 목차와 섹션 헤더의 번역입니다.
TL;DR
문제점(The Problem): 현대 프로젝트는 종종 여러 코딩 에이전트(백엔드, 프론트엔드, 스크립트, 인프라 등)를 동시에 실행합니다. 공유된 조정 구조(coordination fabric)가 없다면, 에이전트들은 서로의 수정을 덮어쓰고, 병렬 작업 흐름에서 발생하는 중요한 컨텍스트를 놓치며, 도구와 팀 간에 사람이 메시지를 전달하도록 요구받습니다.
해결책(The Solution): Agent Mail은 모든 코딩 에이전트에게 영속적인 식별자(예: GreenCastle), 받은 편지함/보낸 편지함(inbox/outbox), 검색 가능한 스레드형 대화, 그리고 수정 의도를 알리기 위한 자문 파일 예약(advisory file reservations, leases)을 제공합니다. 모든 것은 사람이 감사할 수 있는 아티팩트(artifacts)를 위해 Git에 의해 백업되며, 빠른 인덱싱 및 검색을 위해 SQLite가 사용됩니다.
Agent Mail을 사용해야 하는 이유?
| 기능 (Feature) | 역할 (What It Does) | |
|---|
| 자문 파일 예약 (Advisory File Reservations) | 에이전트들이 수정하기 전에 파일 글롭(file globs)에 대한 독점적 또는 공유 임대(leases)를 선언하여, 커밋 전 가드(pre-commit guard)와 충돌하는 것을 방지합니다. | |
| ... | | |
간단한 예시 (Quick Example)
에이전트 대화의 모습
리팩토링을 조정하는 두 에이전트 간의 예시 교환:
┌──────────────────────────────────────────────────────────────────────────────┐
│ 스레드: FEAT-123 - 인증 모듈 리팩토링 (Auth module refactor) │
├──────────────────────────────────────────────────────────────────────────────┤
...
사람의 개입이 필요 없습니다. 에이전트들은 파일 소유권을 협상하고, 호환성 깨지는 변경 사항(breaking changes)을 실시간으로 플래그 지정하며, Git에 저장된 구조화되고 스레드형 메시지를 통해 작업을 인계합니다.
이것이 존재하는 이유 (Why This Exists)
현대 프로젝트는 종종 여러 코딩 에이전트(백엔드, 프론트엔드, 스크립트, 인프라 등)를 동시에 실행합니다. 공유된 조정 구조(coordination fabric)가 없다면, 에이전트들은 서로의 수정을 덮어쓰고, 병렬 작업 흐름에서 발생하는 중요한 컨텍스트를 놓치며, 도구와 팀 간에 사람이 메시지를 전달하도록 요구받습니다.
Agent Mail은 2025년 10월부터 사용 가능했으며, Claude Code, Codex CLI, Gemini CLI와 같은 제공업체 전반의 실제 멀티 에이전트 코딩 워크로드를 중심으로 설계되었습니다. 인접한 Beads 및 bv 도구는 이를 완전한 협업 스택(coordination stack)으로 더 유용하게 만듭니다: Beads는 작업을 추적하고, bv는 다음 적절한 작업을 선택하는 데 도움을 주며, Agent Mail은 협업 트래픽을 전달합니다.
'모두에게 브로드캐스트(broadcast to all)' 모드 부재. 선택지가 주어지면 많은 에이전트들이 브로드캐스트 방식의 메시징을 과도하게 사용할 것입니다. 이는 이메일에서 기본 '회신 모두(reply-all)'와 동일하며, 관련 없는 노이즈가 많고 컨텍스트 낭비로 이어집니다.
세심하게 다듬어진 API 인체공학(ergonomics). 잘못된 MCP 문서화와 낮은 에이전트 인체공학은 조용히 신뢰성을 무너뜨립니다. Agent Mail의 45개 도구 정의는 반복적인 실제 환경 반복 작업을 거쳤기 때문에 토큰을 낭비하지 않고 예측 가능하게 작동합니다.
git worktree 미사용. 워크트리(worktrees)는 에이전트들이 분기할 때 개발 속도를 늦추고 조정 부채(reconciliation debt)를 생성할 수 있습니다. Agent Mail은 정반대의 접근 방식을 취합니다: 에이전트를 하나의 공유 공간에 유지하고, 충돌을 빠르게 노출하며, 이를 통해 협업할 도구를 제공합니다.
하드 락(hard locks) 대신 자문 파일 예약(advisory file reservations). 이 문제에 대해서는 하드 락보다 자문 예약이 더 적합합니다. 에이전트는 작업하는 동안 파일을 임시로 점유할 수 있고, 예약은 자동으로 만료되며, 오래된 점유권은 회수될 수 있습니다. 이는 시스템을 충돌하거나 재설정된 에이전트에도 강건하게(robust) 만듭니다. 하드 락으로는 불가능합니다.
반영구적(Semi-persistent) 식별자. 이 식별자는 개별 작업 기간 동안(협업 목적으로) 지속될 수 있지만, 흔적 없이 사라지면서도 시스템을 망가뜨리지 않는 특성을 가집니다. 전체 시스템을 다운시키는 리더 에이전트(ringleader agents)는 원하지 않습니다. Agent Mail의 식별자는 기억하기 쉬우면서도(GreenCastle 등), 설계상 일시적(ephemeral)입니다.
그래프 인식 작업 선택(Graph-aware task selection). 200~500개의 작업을 가지고 있다면, 에이전트들이 무작위로 작업을 선택하거나 무엇을 해야 할지 소통하며 컨텍스트를 낭비하는 것을 원하지 않을 것입니다. 각 에이전트가 어떤 작업을 수행해야 하는지에 대한 '정답'은 보통 존재하며, 이 정답은 작업의 의존성 구조(dependency structure)에서 나옵니다. 이것이 바로 bv가 그래프 이론을 사용하여 계산하는 것인데, 마치 각 에이전트에게 전체적으로 가장 많은 작업을 해제할 방향을 알려주는 나침반과 같습니다.
Agent Mail이 제공하는 기능
- 충돌 방지: 명시적인 파일 예약(leases)은 파일을 덮어쓰는 충돌을 방지합니다.
- 인간 중개 작업 감소: 에이전트들이 스레드 대화, 확인 응답(acknowledgments), 우선순위 레벨과 함께 서로에게 직접 메시지를 보냅니다.
- 토큰 예산 유지: 프로젝트별 Git 아카이브에 저장되어 에이전트 컨텍스트 창을 소모하지 않습니다.
- 빠른 읽기 제공:
resource://inbox/{Agent}?project=<abs-path>, resource://thread/{id}?project=<abs-path> 및 23개의 다른 MCP 리소스를 제공합니다.
- 완벽한 감사 추적(audit trails) 제공: 모든 지침, 예약(lease), 메시지, 첨부 파일은 인간의 검토를 위해 Git에 기록됩니다.
- 저장소 전반 확장성: 여러 저장소(repo)에 걸쳐 프론트엔드 및 백엔드 에이전트가 제품 버스(product bus)와 연락 시스템을 통해 조정됩니다.
일반적인 사용 사례
- 여러 에이전트가 동기화 상태를 유지하면서 서비스 전반에 걸쳐 대규모 리팩토링을 분할합니다.
- 프론트엔드 및 백엔드 에이전트 팀이 저장소(repository) 전반에 걸쳐 스레드별로 조정됩니다.
- 독점 파일 예약과 프리 커밋 가드(pre-commit guards)를 사용하여 중요한 마이그레이션을 보호합니다.
- 스레드가 발전함에 따라 긴 기술 토론을 검색하고 요약합니다.
- 의존성 인식 작업 선택을 위해 Beads 작업 추적 기능을 사용하여 에이전트 스웜(swarm)을 실행합니다.
생산성 계산 (Productivity Math)
병렬 에이전트 작업은 감독(supervision)의 경제학을 변화시킵니다. 한 명의 인간 운영자가 여러 에이전트를 조종하는 데 1시간을 쓸 수 있는 동안, 해당 에이전트들은 병렬로 수많은 시간 분량의 구현(implementation) 작업을 생산합니다. 정확한 배율은 작업과 워크플로우가 얼마나 체계적인지에 따라 달라지지만, 핵심은 간단합니다. 조정 오버헤드(coordination overhead)가 중요하며, Agent Mail은 이 오버헤드를 낮게 유지하도록 구축되었습니다.
사용자 후기
"Agent Mail과 Beads는 최초의 '에이전트 네이티브(agent-native)' 툴링처럼 느껴집니다."
— @jefftangx
"Agent mail은 처음 접했을 때 정말 정신을 아득하게 만드는 경험입니다. 만들어주셔서 감사합니다."
— @quastora
"Claude Code, Codex CLI, Gemini; Beads; 그리고 Agent Mail 사이에서—기본적으로 자율 기업(autonomous corporation)까지 80% 정도 왔습니다. 이 모든 것이 작동한다는 것이 놀랍습니다!"
— @curious_vii
"Agent mail을 사용하면 == 성배(holy grail)입니다."
— @metapog
"이것에 대한 유일하게 올바른 답은 mcp agent mail입니다."
— @skillcreatorai
"GPT 5.2가 에이전트 조정(agent co-ordination)을 위해 beads + agent mail을 제안합니다 (물론, 저는 이미 사용하고 있습니다)."
— @jjpcodes
설계 철학
채팅이 아닌, 메일 비유(Mail metaphor)입니다. 에이전트는 제목(subjects), 수신자(recipients), 스레드 ID(thread IDs)가 포함된 개별 메시지를 보냅니다. 작업 조정은 명확한 의도를 가진 구조화된 커뮤니케이션이지, 무차별적인 정보의 분출(firehose)이 아닙니다. 직장에서 이메일 시스템이 매번 '전체 회신(reply-all)'으로 기본 설정되어 있다고 상상해 보세요. 채팅 기반 조정이 바로 그런 방식이며, 컨텍스트를 빠르게 소모시킵니다.
SQLite를 라이브 상태(live state)에, Git을 영구 원장(durable ledger)에 사용합니다. 승인된 쓰기 경로는 먼저 SQLite를 변형시키므로, 인박스(inboxes), 리소스(resources), TUI, 웹, 로봇 뷰가 하나의 신선한 운영 상태를 확인하게 됩니다. 이와 동시에 이루어지는 쓰기는 사람의 눈으로 읽을 수 있는 메시지, 프로필, 예약 아티팩트들을 프로젝트별 Git 아카이브에 발행하여 감사 및 복구(audit and recovery)에 사용합니다.
필수 사항이 아닌 권고 사항입니다. 파일 예약은 하드 락(hard locks)이 아닌 자문용 임대(advisory leases)입니다. pre-commit guard가 커밋 시점에 이를 강제하지만, 에이전트는 필요하다면 이 예약을 무시할 수 있습니다. 예약을 획득하는 것은 다른 에이전트가 임대를 해제하기를 기다리는 대신 충돌을 보고합니다. 예약은 TTL(Time To Live)에 따라 만료되며, 스토리지 또는 런타임 계층에서 데드락(deadlocks)을 방지하지는 않습니다.
에이전트 사망에도 탄력적입니다. 에이전트는 끊임없이 죽습니다: 컨텍스트 창 오버플로우, 세션 충돌, 메모리 휘발. 어떤 에이전트든 시스템을 멈추지 않고 사라질 수 있습니다. 리더 에이전트가 없으며, 단일 실패 지점(single points of failure)도 없습니다. 조정(coordination)을 위해 반(semi)-영구적인 ID가 존재하지만, 하드 의존성을 만들지는 않습니다.
듀얼 영속성(Dual persistence). 감사 가능성을 위해 Git에 사람의 눈으로 읽을 수 있는 Markdown 형식을 사용하고; 라이브 인덱싱 및 빠른 어휘적/의미론적 검색을 위해 SQLite와 Search V3를 사용합니다. 둘 다 쓰기 파이프라인을 통해 동기화됩니다.
Tokio 없이 구조적 동시성(Structured concurrency). 전체 비동기 스택은 asupersync와 Cx-스레드 구조적 동시성을 사용합니다. 고아 태스크(orphan tasks)가 없고, 취소 가능하고 정확한 채널(cancel-correct channels)을 가지며, 가상 시간(virtual time)을 이용해 결정론적 테스트가 가능합니다.
Rust 대 Python: 스트레스 테스트 결과
