zhongwei/gh-warrenzhu050413-warren-claude-code-plugin-marketplace-gmail-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:05:24 +08:00
commit 8b82a349e4
5 changed files with 300 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# gmail-plugin
Gmail CLI integration for composing, sending, searching, and managing emails

117
commands/gmail.md Normal file
View File

@@ -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 <message_id> # Summary view
gmail read <message_id> --full # Full content
gmail read <message_id> --full-thread # Full with thread context
gmail thread <message_id> # View entire thread
gmail thread <message_id> --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 <message_id> --body "Reply text"
gmail reply <message_id> --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 <token> 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

119
commands/setup.md Normal file
View File

@@ -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

49
plugin.lock.json Normal file
View File

@@ -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": []
}
}