claude-mail-buddy

Experimental — this is a work in progress and the architecture is still evolving.

An IMAP bridge that forwards emails from a trusted sender as prompts to a running Claude Code instance, and sends replies back via email.

How it works

1. Polls a dedicated IMAP mailbox every 45 seconds for new messages
2. Filters by a configured sender address
3. Formats the email as a prompt and dispatches it to Claude Code via an external paste utility
4. Claude Code processes the message and replies via the CCC send-email action

Dependencies

• imapflow — IMAP client
• mailparser — email parsing
• An external script to deliver the prompt to Claude Code's terminal window. This tool has been tested with claude-code-conduit and a companion paste utility that targets the correct Konsole window via xdotool. CCC also provides the send-email action used for replies.

Configuration

Copy config.example.json to a location outside your workspace (e.g. ~/.secrets/claude-mail-buddy.conf) and fill in your credentials:

{
    "imap": {
        "host": "mail.example.com",
        "port": 993,
        "secure": true,
        "user": "claude-buddy@example.com",
        "pass": "secret",
        "mailbox": "INBOX"
    },
    "allowed_sender": "you@example.com",
    "claude_window_id": 25165857,
    "claude_remote_path": "/path/to/claude-remote.mjs"
}

Override the config path with the MAIL_BUDDY_CONFIG environment variable.

Usage

npm install
node mail-buddy.mjs

Caveats

• IMAP IDLE push notifications are unreliable on some servers (tested on Loopia — falls back to 45s polling)
• The paste mechanism steals window focus on every message; a cleaner PTY-based approach is planned
• Sender filtering is substring-based, not cryptographically verified (DKIM checking is planned)