From 7ddfcbecf4b8dffc25ad408da6fbfaf4c16ba051 Mon Sep 17 00:00:00 2001
From: mikael-lovqvists-claude-agent <mikaels.claude.agent@efforting.tech>
Date: Wed, 18 Mar 2026 03:43:11 +0000
Subject: [PATCH] Add README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5d7f748
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# 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)