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: / Fw: prefixes are stripped automatically and RFC 2047 encoded-word Subjects (Persian, accents) are decoded. In GPG mode the Subject fallback is disabled so a tampered header can't slip past a body-only signature.

  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 four hooks: SessionStart writes the registration row directly to the bus SQLite (deterministic), UserPromptSubmit drains any queued mail into the next turn, 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 — and PreCompact emits a heartbeat event whenever Claude rotates its working memory, so the dashboard's flow panel keeps pulsing across compaction. 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. Multiple agents in the same project? Use spawn <path> as agent-foo to register under an explicit name — the underlying CLAUDE_AGENT_NAME env var threads through the SessionStart hook and proc-scan reconcile so identity stays correct across bus restarts.

  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

    1648 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; opt-in JSON envelope fields on the wire light up app-only affordances (live-agent routing, progress bars, suggested-reply chips) without affecting plain-text email users. Repository link and screenshots coming soon.

  9. № 09

    Read-only tasks skip the dirty-repo gate

    First-time questions and follow-up replies classified as obviously read-only (explain …, show …, list …, plain interrogatives, polite forms like can you explain …) no longer require a clean working tree and no longer fork a per-task branch unless they are continuing a prior task branch. Mutating tasks still require clean for a fresh branch. Classification is conservative — anything ambiguous (e.g. also fix the rest) is treated as mutating. The classifier is regex-only and runs server-side.

  10. № 10

    Email follow-ups continue on the same branch

    When you reply on a thread that came from a prior task's result, the follow-up task reuses the prior task's branch — even if the prior task left it dirty (uncommitted edits from the previous turn are treated as your work in progress). If the repo has unrelated dirty changes on a different branch, the follow-up still fails with a clear "cannot switch safely" message. The lookup walks the SMTP In-Reply-To header back through outbound_emails.task_id; pre-existing rows without that column behave exactly as today.

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

Positioning Compared to Claude Code's Agent View

Claude Code now ships a built-in Agent View — a terminal-side overview of every concurrent session, with inline replies and claude --bg for backgrounded tasks. It is excellent when you are at the laptop. claude-email starts where Agent View stops.

  • Remote-first. Drive every agent from any inbox — phone, web, mutt — without ssh, VPN, or a terminal open. Agent View is local to one machine; an email is not.
  • Inter-agent bus. Agents talk to each other over the MCP chat bus via chat_message_agent, not just to you. Agent View has no agent-to-agent channel.
  • Persistent, multi-surface state. Conversations, task history, and liveness live in SQLite (WAL) and surface on a graphical CRT dashboard at /dashboard, the Android companion (in progress), and the same email thread you started in — across reboots and bus restarts.

In short: Agent View is the cockpit when you're at the laptop; claude-email is the radio when you're not.

04

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.