commit 8b82a349e4d66b917ce99e5a7011525b7438d748 Author: Zhongwei Li Date: Sun Nov 30 09:05:24 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..78ef3ab --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "gmail-plugin", + "description": "Gmail CLI integration for composing, sending, searching, and managing emails", + "version": "1.0.0", + "author": { + "name": "Fucheng Warren Zhu", + "email": "wzhu@college.harvard.edu" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..5cb3064 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# gmail-plugin + +Gmail CLI integration for composing, sending, searching, and managing emails diff --git a/commands/gmail.md b/commands/gmail.md new file mode 100644 index 0000000..b9dd9db --- /dev/null +++ b/commands/gmail.md @@ -0,0 +1,117 @@ +--- +description: Guide for using the gmail CLI to send, search, and manage emails +--- + +# Gmail CLI Usage Guide + +Use the `gmail` CLI for all email operations. + +## Quick Reference + +### Search & Discovery +```bash +gmail search "to:person@example.com" --max 10 # Emails to someone +gmail search "from:person@example.com" --max 10 # Emails from someone +gmail search "subject:keyword after:2024/10/01" # By subject + date +gmail search "has:attachment filename:pdf" # With attachments +gmail list --folder INBOX --max 10 # List inbox +gmail folders # List all folders/labels +``` + +### Read & View +```bash +gmail read # Summary view +gmail read --full # Full content +gmail read --full-thread # Full with thread context +gmail thread # View entire thread +gmail thread --strip-quotes # Thread without quoted content +``` + +### Send & Reply +```bash +# Send from file (preferred for composed emails) +gmail send --to user@example.com --subject "X" --body "$(cat /tmp/email/draft.txt)" +gmail send --to user@example.com --subject "X" --body "$(cat /tmp/email/draft.txt)" --attachment file.pdf + +# Send inline (for quick messages) +gmail send --to user@example.com --subject "X" --body "Y" +gmail reply --body "Reply text" +gmail reply --body "Reply" --reply-all +``` + +### Email Styles +```bash +gmail styles list # List all styles +gmail styles show professional-formal # View specific style +gmail styles validate style-name # Validate format +``` + +**Common styles:** `professional-formal`, `professional-friendly`, `casual-friend`, `brief-reply` + +### Email Groups +```bash +gmail groups list # List all groups +gmail groups show team # Show group members +gmail groups add team person@example.com # Add member +gmail send --to @team --subject "X" --body "Y" # Use group +``` + +### Workflows +```bash +gmail workflows list # List workflows +gmail workflows run clear # Run interactively +gmail workflows start clear # Start programmatic (JSON) +gmail workflows continue archive # Continue with action +``` + +## Gmail Search Operators + +**People:** `from:`, `to:`, `cc:`, `bcc:` +**Date:** `after:YYYY/MM/DD`, `before:YYYY/MM/DD`, `newer_than:7d`, `older_than:30d` +**Status:** `is:unread`, `is:starred`, `is:important`, `is:read` +**Content:** `subject:keyword`, `has:attachment`, `has:drive`, `filename:pdf` +**Size:** `larger:10M`, `smaller:5M` +**Boolean:** `OR`, `-` (NOT), `()` (grouping) + +**Examples:** +- All correspondence: `to:person@example.com OR from:person@example.com` +- Recent thread: `subject:project after:2024/10/01` +- Unread important: `is:unread is:important` +- With PDF: `has:attachment filename:pdf` + +## Composing Emails - Best Practices + +### Before Writing +1. **Search past emails** to recipient to extract greeting/tone/sign-off patterns +2. **Check email styles** with `gmail styles list` to match context +3. **Always test** to fuchengwarrenzhu@gmail.com before real sends + +### Workflow +1. Draft email to `/tmp/email/{descriptive_name}.txt` +2. Open file for user review with `open /tmp/email/{name}.txt` +3. Test send: `gmail send --to fuchengwarrenzhu@gmail.com --subject "..." --body "$(cat /tmp/email/{name}.txt)" --yolo` +4. After user confirms, send to real recipient + +## Configuration + +- **Config directory:** `~/.gmaillm/` +- **Email styles:** `~/.gmaillm/email-styles/` +- **Email groups:** `~/.gmaillm/email-groups.json` +- **Credentials:** `~/.gmaillm/credentials.json` + +## Troubleshooting + +```bash +# Verify setup +gmail verify + +# Check account status +gmail status + +# Re-authenticate if needed +gmail setup-auth +``` + +## Related Commands + +- `/gmail:setup` - Set up Gmail CLI authentication diff --git a/commands/setup.md b/commands/setup.md new file mode 100644 index 0000000..e55e5b3 --- /dev/null +++ b/commands/setup.md @@ -0,0 +1,119 @@ +--- +description: Set up Gmail CLI authentication with OAuth2 +--- + +# Gmail CLI Setup + +This command guides you through setting up the `gmail` CLI for the first time. + +## Prerequisites + +You need OAuth2 credentials from Google Cloud Console. + +## Step 1: Get OAuth2 Credentials + +1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials) +2. Create a new project or select an existing one +3. Enable the **Gmail API**: + - Go to "APIs & Services" > "Enable APIs and Services" + - Search for "Gmail API" and enable it +4. Create OAuth2 credentials: + - Go to "Credentials" > "Create Credentials" > "OAuth client ID" + - Application type: **Desktop app** + - Name: "Gmail CLI" (or any name) + - Click "Create" +5. Download the credentials JSON file +6. Save it as `~/.gmaillm/oauth-keys.json`: + ```bash + mkdir -p ~/.gmaillm + mv ~/Downloads/client_secret_*.json ~/.gmaillm/oauth-keys.json + chmod 600 ~/.gmaillm/oauth-keys.json + ``` + +## Step 2: Install gmaillm + +```bash +# Install from source +cd /Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/gmail-integration-plugin/scripts/gmaillm +make install +``` + +## Step 3: Authenticate + +Run the setup command: +```bash +gmail setup-auth +``` + +This will: +1. Open your browser for Google authentication +2. Ask you to grant Gmail access to the CLI +3. Save credentials to `~/.gmaillm/credentials.json` + +**If port 8080 is in use:** +```bash +gmail setup-auth --port 8081 +``` + +## Step 4: Verify Installation + +```bash +gmail verify +``` + +Expected output: +``` +Gmail API authentication: OK +``` + +## Troubleshooting + +### "Credentials file is empty" Error +```bash +# Re-run authentication +python3 -m gmaillm.setup_auth + +# If port is blocked +python3 -m gmaillm.setup_auth --port 9999 +``` + +### "Address already in use" Error +```bash +# Kill any existing auth processes +pkill -f "gmaillm.setup_auth" + +# Try a different port +gmail setup-auth --port 8081 +``` + +### OAuth Keys Location +The CLI searches for OAuth keys in this order: +1. `~/.gmaillm/oauth-keys.json` (recommended) +2. `${CLAUDE_PLUGIN_ROOT}/credentials/oauth-keys.json` (plugin mode) +3. `~/Desktop/OAuth2/gcp-oauth.keys.json` (fallback) + +## File Structure After Setup + +``` +~/.gmaillm/ +├── oauth-keys.json # OAuth2 client secrets (0600) +├── credentials.json # Saved credentials (0600) +├── email-groups.json # Email distribution groups +├── output-style.json # Output formatting preferences +└── email-styles/ # Email style templates + ├── professional-formal.md + ├── professional-friendly.md + └── casual-friend.md +``` + +## Optional: Shell Completion + +Enable tab completion for faster typing: +```bash +gmail --install-completion +exec $SHELL +``` + +## Related Commands + +- `/gmail` - Usage guide for gmail CLI diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..44391e1 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,49 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace:gmail-plugin", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "7a410db1fe5927e0d70b69091ea1db173a0793c8", + "treeHash": "7f8aeeee68bad905d6ce60f365edb69b552957511f4966bde91bc4c4899da43c", + "generatedAt": "2025-11-28T10:12:56.692757Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "gmail-plugin", + "description": "Gmail CLI integration for composing, sending, searching, and managing emails", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "a872dbc6ad504ca36c70d39d6a7b282259b125b6038f917aaaa099abe1aae226" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "74f3a5bd791de228326cc58fec66997bf91a4f98be4e162a23ae97ead80d4186" + }, + { + "path": "commands/gmail.md", + "sha256": "3093ca819d7f45275a5c30a7a788edfd130ec8b5b850d1764d4bfd152dc5315e" + }, + { + "path": "commands/setup.md", + "sha256": "4a39cde95f6d8e59ff6e2520cab46984bdc9514d49bcea0e90a1991ec7f1eb1f" + } + ], + "dirSha256": "7f8aeeee68bad905d6ce60f365edb69b552957511f4966bde91bc4c4899da43c" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file