claude-email  ·  v1 · OSS
فارسی
Dispatch №001 · Email → Agent

claude-email a correspondence with your agents

Write to Claude the way you write to a colleague — from your inbox.

An email-driven wrapper for the Claude Code CLI with an integrated MCP chat relay. Poll IMAP, verify senders with GPG or a shared secret, execute commands, and reply by SMTP. One wrapper, many agents, any email client.

Open the Repository
01

The Feature Set Why write to a bot by email

  1. № 01

    Email as Terminal

    Any mail client becomes a universal remote for Claude Code. Send a command, receive the result threaded as a reply. No app install. No VPN. Just a stamp and a keyboard. Subject-only mails from a phone are accepted as commands when the body is empty — Re: / Fwd: prefixes are stripped automatically.

  2. № 02

    Dual Authentication

    Every incoming message is verified by From, Return-Path, and either a GPG signature or a rotating shared secret. Unsigned mail from strangers is dropped on sight.

  3. № 03

    Multi-Agent Chat Bus

    An MCP SSE server backed by SQLite (WAL mode) lets many Claude Code agents coordinate through a shared message relay. Cheap, local, and boring enough to be reliable.

  4. № 04

    Agent Orchestration

    Target any agent by @agent-name, spawn a new one against a project path, or broadcast. Threading, liveness checks, and reaping are handled for you. Every project the orchestrator touches gets three hooks: SessionStart writes the registration row directly to the bus SQLite (deterministic), UserPromptSubmit drains any queued mail into the next turn, and Stop drains again at the end of every response — emitting decision:block when peer messages are pending so the stop is cancelled and the messages become the agent's next turn. Agents pick up messages even when they weren't polling, and peer messages that arrive mid-response don't wait until the next user prompt. And agents can talk to each other via chat_message_agent — peer-to-peer notifications without round-tripping through the user.

  5. № 05

    User-Level Systemd

    Two lightweight services, no sudo, no container. Auto-restart, dependency ordering between email and chat, and lingering so it survives logout.

  6. № 06

    Tested to the Margins

    992 tests, 100% coverage, Python 3.12, fully typed, shell=False everywhere, verified TLS contexts. Boring on purpose; invasive vectors locked out.

  7. № 07

    Live Observatory Dashboard

    A fully graphic dashboard at /dashboard renders the bus as a CRT radar: the user sits at centre, agents orbit on a ring, and every message fires a glowing pulse along the chord from sender to recipient. Persistent heat edges mark high-traffic channels, a transmission log streams the bodies live over an EventSource, and clicking any node filters the feed. Two more faces sit behind topbar toggles: a live technical-flow diagram that lights up step cards in real time when wake_watcher spawns an agent or a drain hook fires, and a searchable glossary panel that indexes every acronym and term the project uses. Ghost agents whose heartbeat is stale are filtered out so the radar reflects reality.

  8. № 08

    Android Companion (in progress)

    A native Android app is being built in a separate companion repository so you can dispatch commands and reply to agents from a phone without composing them through a generic mail client. Same IMAP/SMTP backbone, no server-side changes. Repository link and screenshots coming soon.

02

Mechanics How a letter becomes a task

Two user-level systemd services do the work. claude-email polls an IMAP mailbox every few seconds, validates the sender, extracts a command from the body, and runs it through claude --print. The result comes back as a threaded reply.

claude-chat is a pure MCP message bus. Agents register, send, and poll through MCP tools over SSE. The email service also acts as your avatar on that bus — routing commands into agents, and carrying agent answers out as email.

Think of it less as a chatbot and more as an old telegraph exchange: operators relaying traffic, every message signed, every hop logged.

Email Client ↓ IMAP Poll (claude-email) ↓ Verify sender (GPG / shared secret) ↓ ├─ Direct → claude --print ────────→ SMTP reply └─ Chat → MCP bus (claude-chat) ↓ Agents respond ────────→ SMTP reply
03

Getting Started Install & post your first letter

Clone the repository and run the installer:

git clone https://github.com/cocodedk/claude-email.git
cd claude-email
cp .env.example .env    # fill in IMAP/SMTP credentials + AUTHORIZED_SENDER
bash install.sh         # creates venv + both systemd services

The installer provisions a Python virtual environment, installs dependencies, and registers claude-email and claude-chat as user-level systemd services with the correct dependency order.

# Check service status
systemctl --user status claude-email
systemctl --user status claude-chat

# Follow the logs
journalctl --user -u claude-email -f

From that point on, anything you email to your configured address — from your signed sender, in the required format — is executed by Claude and replied to. You can compose commands from a phone, an inbox, or mutt. No app required.