mirror of
https://github.com/gnekt/My-Brain-Is-Full-Crew.git
synced 2026-09-13 09:16:46 +00:00
Add Hey CLI as alternative email backend for Postman (#14)
* Add Hey CLI support as alternative email backend The Postman agent now supports two email backends: - Hey (hey CLI) for Hey.com accounts with pre-sorted mailboxes - GWS (gws CLI) for Gmail/Google Workspace accounts Hey's mailbox model (Imbox, Feed, Paper Trail, Reply Later, Set Aside, Bubble Up) is mapped to triage behaviours so the agent leverages Hey's existing sorting. Calendar operations remain on GWS. All MCP function references replaced with CLI equivalents. No user-specific details in the agent file. * Update agents in postman.md by removing two roles Removed descriptions for Food Coach and Wellness Guide agents from the postman documentation. * Add Hey CLI as email backend across all docs, skills, and references - Resolve all merge conflicts in postman.md keeping GWS + MCP + Hey - Apply all 7 review comments from PR #14 (complete mailbox list, concrete email_backend setting, consistent template placeholders, Hey ID clarification, productivity features disclaimer, deadline body scanning, remove user-specific agent references) - Add Hey CLI alongside GWS/MCP in: README, CLAUDE.md, TERMS_OF_USE, DISCLAIMERS, getting-started, gws-setup-guide (renamed sections), agents-registry, agents.md, onboarding skill, launchme.sh - Update all 4 Postman-related skills (email-triage, deadline-radar, meeting-prep, weekly-agenda) with Hey CLI commands and backend detection - Expand security section to cover Hey CLI injection vectors - Keep MCP as read-only fallback for all backends * Address Copilot review: fix typos, injection rules, platform compat, install hooks - Fix hey imbox --json typo → hey box imbox --json - Fix after:{{yesterday}} → newer_than:2d for consistent 48h scan - Reconcile shell injection rules with hey reply/compose -m (user-approved text only, with safe quoting guidance) - Separate email write ops (GWS/Hey) from calendar write ops (GWS only) in TERMS_OF_USE and DISCLAIMERS - Replace grep -P with POSIX-compatible tab detection in validate-frontmatter - Add hooks/ and settings.json installation to launchme.sh and updateme.sh so .claude/hooks/ paths in settings.json resolve correctly --------- Co-authored-by: gnekt <dima9610@gmail.com>
This commit is contained in:
lh
@@ -72,11 +72,11 @@ This is a tool for self-care and personal organization. If you fork it, please k
|
||||
|
||||
## On privacy and data protection (GDPR and applicable laws)
|
||||
|
||||
> **Read this carefully before using the Postman agent or any feature that accesses external data sources.**
|
||||
> **Read this carefully before using the Postman agent or any feature that accesses external data sources (Gmail, Hey.com, Google Calendar).**
|
||||
|
||||
**This software is designed exclusively for personal, private use on your own data.**
|
||||
|
||||
This project can access your Gmail inbox and Google Calendar through the Google Workspace CLI (`gws`) or MCP connectors, and saves content from those sources as notes inside your local Obsidian vault. **You are solely responsible for ensuring that your use of this software complies with all applicable privacy and data protection laws**, including but not limited to:
|
||||
This project can access your email inbox (Gmail via the Google Workspace CLI or MCP connectors, Hey.com via the Hey CLI) and Google Calendar, and saves content from those sources as notes inside your local Obsidian vault. **You are solely responsible for ensuring that your use of this software complies with all applicable privacy and data protection laws**, including but not limited to:
|
||||
|
||||
- The **EU General Data Protection Regulation (GDPR)**, Regulation (EU) 2016/679
|
||||
- The **California Consumer Privacy Act (CCPA)**
|
||||
@@ -97,15 +97,15 @@ This project can access your Gmail inbox and Google Calendar through the Google
|
||||
|
||||
## On email and calendar write operations
|
||||
|
||||
> **Read this carefully if you enable the Google Workspace CLI (`gws`), which grants the Postman agent full read/write access to your Gmail and Google Calendar.**
|
||||
> **Read this carefully if you enable the Google Workspace CLI (`gws`) or Hey CLI (`hey`), which grant the Postman agent read/write access to your email (and calendar, for GWS).**
|
||||
|
||||
With `gws` enabled, the Postman agent can **send emails, archive emails, delete emails, modify labels, and create/modify/delete calendar events** on your behalf. This means:
|
||||
With `gws` and/or `hey` enabled, the Postman agent can **send emails, reply to threads, archive emails, delete emails, modify labels, and mark as seen/unseen** on your behalf. With `gws` specifically, it can also **create/modify/delete Google Calendar events** (Hey CLI does not operate on Google Calendar). This means:
|
||||
|
||||
- **Emails can be sent from your account.** An email sent by the AI is indistinguishable from one you sent yourself. If the AI misunderstands your intent, drafts an inappropriate response, or hallucinates content, that email goes out with your name on it. Always review drafts before confirming.
|
||||
- **Emails can be archived or deleted.** You might miss important emails if the AI archives or trashes them prematurely. Check your Trash and Archive regularly.
|
||||
- **Calendar events can be created, modified, or deleted.** Incorrect dates, times, or participants could lead to missed meetings or scheduling conflicts.
|
||||
- **Adversarial emails are a real risk.** A malicious email could contain text designed to trick the AI into performing actions you didn't intend — sending a reply, forwarding content, deleting messages, or creating events. The software includes defenses against this (prompt-level security rules, mandatory user confirmation), but **no prompt-based defense is 100% reliable.** The AI model is a stochastic system that may not follow safety instructions in all cases.
|
||||
|
||||
**The MCP fallback (`.mcp.json`) is read-only by design.** If you want email/calendar access without write risks, use MCP instead of `gws`. MCP can read emails, create drafts, and read calendar events, but it cannot send, archive, delete, or modify anything.
|
||||
**The MCP fallback (`.mcp.json`) is read-only by design.** If you want email/calendar access without write risks, use MCP instead of `gws` or `hey`. MCP can read emails, create drafts, and read calendar events, but it cannot send, archive, delete, or modify anything.
|
||||
|
||||
**I built the confirmation gates and security rules to be as strict as I could.** But I'm not a security expert, and prompt-based security has fundamental limits. **Use write access at your own risk, review everything before confirming, and back up anything you can't afford to lose.**
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Postman
|
||||
|
||||
> Your bridge between Gmail, Google Calendar, and your vault.
|
||||
> Your bridge between email (Gmail or Hey.com), Google Calendar, and your vault.
|
||||
|
||||
## What it does
|
||||
|
||||
The Postman connects your email and calendar to your Obsidian vault. It scans your Gmail inbox, identifies what actually matters (action requests, deadlines, important information), and saves it as structured notes. It imports Google Calendar events as meeting prep notes. It can even create new calendar events from your vault content.
|
||||
The Postman connects your email and calendar to your Obsidian vault. It scans your inbox (Gmail via GWS CLI, Hey.com via Hey CLI, or Gmail via MCP as read-only fallback), identifies what actually matters (action requests, deadlines, important information), and saves it as structured notes. It imports Google Calendar events as meeting prep notes. It can even create new calendar events from your vault content.
|
||||
|
||||
The Postman is a smart filter, not a bulk importer. It knows the difference between a critical email from a client requesting a proposal and a marketing newsletter. It recognizes deadlines, extracts action items, and creates notes with the right priority level. Everything it skips, it tells you about, so you stay informed without your vault getting flooded with noise.
|
||||
The Postman is a smart filter, not a bulk importer. It knows the difference between a critical email from a client requesting a proposal and a marketing newsletter. It recognizes deadlines, extracts action items, and creates notes with the right priority level. Everything it skips, it tells you about, so you stay informed without your vault getting flooded with noise. When using Hey, the Postman leverages Hey's pre-sorted mailboxes (Imbox, Feed, Paper Trail, Reply Later, Set Aside, Bubble Up) for smarter triage.
|
||||
|
||||
It works in four modes: email triage (scan and save important emails), calendar import (bring upcoming events into your vault), event creation (schedule something from a note or request), and targeted search (find specific emails or events on a topic).
|
||||
|
||||
@@ -25,7 +25,7 @@ What the Postman agent still does directly:
|
||||
|
||||
- **Calendar import**: pulls upcoming Google Calendar events into the vault as meeting prep notes with participant lists and agenda
|
||||
- **Event creation**: creates Google Calendar events from your requests or from deadlines found in vault notes
|
||||
- **Targeted search**: searches Gmail or Calendar for specific topics, people, or date ranges
|
||||
- **Targeted search**: searches email (Gmail or Hey) or Calendar for specific topics, people, or date ranges
|
||||
- **VIP filter**: prioritizes emails from important contacts (colleagues, clients, key people)
|
||||
- **Email drafting**: drafts reply emails based on vault context
|
||||
- **Travel mode**: when it detects travel-related events (flights, hotels, conferences), creates a consolidated travel itinerary note
|
||||
@@ -57,7 +57,7 @@ In German: "Prufe meine Emails", "Was steht im Kalender"
|
||||
|
||||
**You:** Check my email
|
||||
|
||||
**Postman:** Scanning your Gmail inbox... Found 28 unread messages.
|
||||
**Postman:** Scanning your inbox... Found 28 unread messages.
|
||||
|
||||
Saved to vault (3):
|
||||
- **"Proposal Request From Luca"**: action required, high priority. Luca needs a project proposal by next Wednesday. Saved with action items and deadline.
|
||||
@@ -131,7 +131,7 @@ Shall I proceed?
|
||||
- **Let it create calendar events from notes.** If a note contains a deadline or meeting plan, tell the Postman to schedule it. Saves you switching to Google Calendar.
|
||||
- **Trust the noise filter.** The Postman is aggressive about filtering newsletters, notifications, and receipts. If it ever filters something important, tell it. It learns from your corrections.
|
||||
- **Check "needs your input" items.** The Postman flags ambiguous emails rather than guessing. These are usually worth a quick look.
|
||||
- **Make sure Gmail and Google Calendar are connected.** The Postman needs API access to your accounts. Check `Meta/user-profile.md` to verify integrations are enabled, or ask the Architect during onboarding.
|
||||
- **Make sure at least one email backend is connected.** The Postman needs either GWS (`gws`), Hey CLI (`hey`), or MCP connectors to access your email. Check `Meta/user-profile.md` to verify integrations are enabled (including the `email_backend` setting if you have multiple backends), or ask the Architect during onboarding.
|
||||
|
||||
## What it remembers
|
||||
|
||||
|
||||
@@ -13,7 +13,8 @@ A step-by-step guide for setting up your AI-powered vault. No technical backgrou
|
||||
- **Git**: A tool to download the project. On Mac, the terminal will prompt you to install it automatically the first time you use it. On Windows, download it from [git-scm.com](https://git-scm.com).
|
||||
|
||||
### Optional (but recommended)
|
||||
- **Gmail account**: If you want the Postman agent to process your emails
|
||||
- **Gmail account**: If you want the Postman agent to process your Gmail inbox (via GWS CLI or MCP)
|
||||
- **Hey.com account**: If you use Hey for email (via Hey CLI) — works alongside or instead of Gmail
|
||||
- **Google Calendar**: If you want calendar integration
|
||||
|
||||
---
|
||||
@@ -89,7 +90,7 @@ bash scripts/launchme.sh
|
||||
|
||||
The script will ask two quick questions:
|
||||
1. **Is this your vault folder?** Confirm or enter the correct path
|
||||
2. **Do you use Gmail or Google Calendar?** Choose yes to set up the Postman integration
|
||||
2. **Do you use Gmail, Hey.com, or Google Calendar?** Choose yes to set up the Postman integration
|
||||
|
||||
When it's done, your vault will look like this:
|
||||
|
||||
@@ -144,8 +145,8 @@ The `/onboarding` skill will kick in and the **Architect** will start a friendly
|
||||
- What areas of your life do you want to manage?
|
||||
|
||||
### About integrations (optional)
|
||||
- Do you want email triage? (requires Gmail connection)
|
||||
- Do you want calendar integration? (requires Google Calendar connection)
|
||||
- Do you want email triage? (requires Gmail via GWS/MCP, or Hey.com via Hey CLI)
|
||||
- Do you want calendar integration? (requires Google Calendar via GWS/MCP)
|
||||
|
||||
After the conversation, the Architect creates your entire vault structure, saves your profile, and leaves you a personalized welcome note.
|
||||
|
||||
@@ -174,7 +175,7 @@ The **Scribe** detects multiple items and creates separate notes for each.
|
||||
### Check your email
|
||||
> "Check my email for anything important"
|
||||
|
||||
The `/email-triage` skill scans your Gmail, saves actionable emails, and gives you a summary.
|
||||
The `/email-triage` skill scans your inbox (Gmail or Hey.com), saves actionable emails, and gives you a summary.
|
||||
|
||||
### File everything
|
||||
> "Triage my inbox"
|
||||
@@ -212,8 +213,8 @@ The Crew works best with simple daily routines:
|
||||
### "The agent doesn't seem to activate"
|
||||
Make sure Claude Code is open inside your vault folder (not a different directory). Verify agent files exist at `.claude/agents/` and skill files at `.claude/skills/` in your vault. Try saying the trigger phrase differently. Agents and skills understand natural language in multiple languages.
|
||||
|
||||
### "Gmail/Calendar isn't working"
|
||||
The Postman needs Gmail and Google Calendar MCP connectors. Run the installer again (`bash scripts/launchme.sh`) and answer **yes** to the Gmail/Calendar question, or manually copy `.mcp.json` from the repo to your vault root. Then authorize the connection when Claude Code prompts you.
|
||||
### "Email/Calendar isn't working"
|
||||
The Postman needs at least one email backend: GWS CLI (`gws`), Hey CLI (`hey`), or MCP connectors. For GWS, see `docs/gws-setup-guide.md`. For Hey, install from [github.com/basecamp/hey-cli](https://github.com/basecamp/hey-cli) and run `hey auth login`. For MCP, run the installer again (`bash scripts/launchme.sh`) and answer **yes** to the Gmail/Calendar question, or manually copy `.mcp.json` from the repo to your vault root.
|
||||
|
||||
### "My vault structure looks different from the docs"
|
||||
The Architect customizes the structure based on your onboarding answers.
|
||||
|
||||
@@ -1,8 +1,54 @@
|
||||
# Setting Up Google Workspace CLI for the Postman Agent
|
||||
# Setting Up Email Backends for the Postman Agent
|
||||
|
||||
The Postman agent supports three email backends. You can use one or more:
|
||||
|
||||
| Backend | Email Provider | Access Level | Calendar |
|
||||
|---------|---------------|-------------|----------|
|
||||
| **GWS CLI** (`gws`) | Gmail / Google Workspace | Full read/write | Yes (Google Calendar) |
|
||||
| **Hey CLI** (`hey`) | Hey.com | Full read/write | No (Hey has its own productivity tools, not Google Calendar) |
|
||||
| **MCP connectors** | Gmail | Read-only + drafts | Read-only (Google Calendar) |
|
||||
|
||||
If you have both Gmail and Hey.com, you can use `gws` and `hey` simultaneously. Set your preferred primary backend in `Meta/user-profile.md` with `email_backend: hey` or `email_backend: gws` (default: `gws`).
|
||||
|
||||
---
|
||||
|
||||
## Option A: Hey CLI (for Hey.com users)
|
||||
|
||||
### Step 1: Install Hey CLI
|
||||
|
||||
```bash
|
||||
# See https://github.com/basecamp/hey-cli for the latest instructions
|
||||
gem install hey-cli
|
||||
```
|
||||
|
||||
### Step 2: Authenticate
|
||||
|
||||
```bash
|
||||
hey auth login
|
||||
```
|
||||
|
||||
### Step 3: Verify
|
||||
|
||||
```bash
|
||||
hey auth status --json
|
||||
hey box imbox --json --limit 1
|
||||
```
|
||||
|
||||
If both return JSON, you're good. The Postman will auto-detect `hey` on PATH.
|
||||
|
||||
### Troubleshooting Hey
|
||||
|
||||
- **`hey: command not found`**: ensure the gem bin directory is on your PATH. Check with `gem environment` and add `<gem_dir>/bin` to PATH.
|
||||
- **Auth expired**: run `hey auth refresh` or `hey auth login`.
|
||||
- **General issues**: run `hey doctor` for diagnostics.
|
||||
|
||||
---
|
||||
|
||||
## Option B: Google Workspace CLI (for Gmail users)
|
||||
|
||||
The Postman agent uses the [Google Workspace CLI](https://github.com/googleworkspace/cli) (`gws`) to interact with Gmail and Google Calendar. This gives the agent full read/write access — searching, reading, archiving, deleting, labelling emails, and creating/modifying calendar events.
|
||||
|
||||
## Why gws instead of MCP?
|
||||
### Why gws instead of MCP?
|
||||
|
||||
The Anthropic-hosted MCP servers for Gmail and Calendar are read-only (plus draft creation). They cannot archive, delete, label, or send emails. The Google Workspace CLI wraps the full Google API surface, giving the Postman agent the ability to actually manage your inbox — not just read it.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user