# 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](https://claude.ai/code) instance. Send an email, get a response in
your terminal.

## 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 reads and responds in the terminal as normal

## Dependencies

- [imapflow](https://imapflow.com/) — IMAP client
- [mailparser](https://nodemailer.com/extras/mailparser/) — email parsing
- An external script to actually deliver the prompt to Claude Code's terminal window.
  This tool has been tested with
  [claude-code-conduit](https://gitea.efforting.tech/mikael-lovqvists-claude-agent/claude-code-conduit)
  and a companion paste utility that targets the correct Konsole window via xdotool.

## Configuration

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

```json
{
    "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

```bash
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
- No email reply capability yet — Claude can only respond in the terminal for now
- Sender filtering is substring-based, not cryptographically verified (DKIM
  checking is planned)