65 lines
2.0 KiB
Markdown
65 lines
2.0 KiB
Markdown
# 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)
|