A terminal-based AI email assistant that manages an inbox via agentmail.to. When emails arrive, a Claude agent decides how to handle them: reply directly, ask you for guidance, or discard spam. The agent maintains per-contact context files so it remembers past conversations.
- Install dependencies:
bun install- Add your AgentMail API key to
.env:
AGENTMAIL_API_KEY=am_...
The Claude agent runs via your Max subscription — no separate Anthropic API key needed.
- Configure
config.yamlwith your inbox address and personal info:
inbox:
address: "donna.office@agentmail.to"
user:
name: "Joachim"
email: "joachim@example.com"bun run src/index.tsThe app will print the inbox address and start polling for new emails. Press Ctrl+C to stop.
The agent polls the inbox every 15 seconds (configurable). For each new email it:
- Fetches the full thread
- Loads any contact-specific config and interaction history
- Builds a prompt with all relevant context
- Runs a Claude Sonnet agent that decides what to do
- Labels the message as processed
The agent has three actions available:
- Reply — sends a reply on your behalf, signing as your assistant
- Ask you — prints a question to the terminal and waits for your typed answer
- Discard — marks spam/irrelevant emails and moves on
After meaningful interactions, the agent automatically saves a summary to context/ so it remembers past conversations with each contact.
This is the base instruction set for the agent. Edit it to change how the agent decides what to reply, when to ask you, and what to discard. You can adjust tone, add rules, or change the decision framework entirely.
Create YAML files to give the agent per-sender or per-domain instructions:
# contacts/acme.com.yaml
name: "Acme Corp"
relationship: "Client"
tone: "Professional"
instructions: |
- Always CC pm@acme.com
- Never discuss pricing without owner approvalLookup order: exact email (contacts/john@acme.com.yaml) then domain (contacts/acme.com.yaml).
The agent maintains markdown files in context/ with dated summaries of past interactions per sender. These are loaded automatically when processing emails from that sender. You can also edit these files manually to seed context or correct the agent's memory.
This directory is gitignored.
| Setting | Description |
|---|---|
inbox.address |
Your agentmail inbox (set once) |
polling.interval_seconds |
How often to check for new mail |
agent.model |
Claude model to use (default: claude-sonnet-4-6) |
agent.max_turns |
Max agent turns per email |
user.name |
Your name (used when signing replies) |
user.email |
Your email (included in agent context) |
The agent currently only processes incoming emails reactively. It cannot:
- Send emails on your behalf unprompted
- Schedule or delay replies
- Handle attachments
To add these or other capabilities, extend the tools in src/tools.ts.