gmail-watcher
Skill1 starsChanged 52 days agoMITView on GitHub
Monitor Gmail inbox for important and unread emails using Gmail API. Automatically creates action files in /Needs_Action for Claude to process. Use when you need to detect and respond to important emails, create email-based workflows, or integrate email monitoring into the AI Employee system.
- Reads credentials
2 other projects use a version of this.
Adopted by
Most recently taken up by
- muhammad-anas35/AI-Employee-Gold-tierword for word, first seen Sep 25, 2026
- omerfarooq223/personal-ai-employeetheir own version, first seen Mar 19, 2026
Other versions2 projects use a version of this.
Word for word · 1
- muhammad-anas35/AI-Employee-Gold-tier★ 1100% same
Edited · 0
None found.
Wrote their own version · 1
- omerfarooq223/personal-ai-employee★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- odoo-integrationSkill
- browsing-with-playwrightSkill
- send-emailSkill
- process-vault-tasksSkill
- facebook-posterSkill
- linkedin-posterSkill
- update-dashboardSkill
- whatsapp-watcherSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 9 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 44
Create a new project or select existing
- Distinctive: line 48
Place in project root
- Very specific: line 188
Never commit credentials.json or token.json
- Distinctive: line 194
No external logging or analytics
- Distinctive: line 200
Default: 1 check per 2 minutes
- Distinctive: line 214
Wait 1-2 minutes for propagation
- Distinctive: line 218
Check Gmail query filter
- Distinctive: line 219
Verify emails match criteria (unread + important)
- Very specific: line 220
Check .processed_emails for duplicates
- Distinctive: line 223
Check logs for errors
- Distinctive: line 225
Use process manager (PM2) for auto-restart
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Gmail Watcher
Monitor Gmail inbox for important and unread emails, automatically creating action files in the vault for Claude to process.
Overview
This skill continuously monitors your Gmail inbox using the Gmail API, detecting important or unread emails and creating structured action files in /Needs_Action for processing.
Usage
# Start the Gmail watcher
python scripts/gmail_watcher.py
# Test mode (dry run)
python scripts/gmail_watcher.py --test
# Custom check interval (seconds)
python scripts/gmail_watcher.py --interval 300What It Does
- Monitors Gmail using Gmail API every 2 minutes (configurable)
- Filters for unread and important emails
- Creates action files in
/Needs_Action/EMAIL_*.md - Tracks processed emails to avoid duplicates
- Logs all activity to
/Logs/gmail_watcher.log
Prerequisites
Gmail API Setup
- Go to Google Cloud Console
- Create a new project or select existing
- Enable Gmail API
- Create OAuth 2.0 credentials
- Download credentials as
credentials.json - Place in project root
First Run Authentication
# First run will open browser for OAuth consent
python scripts/gmail_watcher.py
# This creates token.json for future runs
# Keep token.json secure and never commit itConfiguration
Environment Variables
# .env file
GMAIL_CREDENTIALS_PATH=./credentials.json
GMAIL_TOKEN_PATH=./token.json
VAULT_PATH=./AI_Employee_Vault
CHECK_INTERVAL=120 # secondsGmail Query Filters
Default query: is:unread is:important
Customize in gmail_watcher.py:
# Monitor specific labels
query = 'is:unread label:clients'
# Monitor from specific senders
query = 'is:unread from:important@client.com'
# Monitor with keywords
query = 'is:unread (invoice OR payment OR urgent)'Action File Format
Created files follow this structure:
---
type: email
from: sender@example.com
subject: Invoice Request
received: 2026-03-12T20:23:44Z
priority: high
status: pending
message_id: abc123xyz
---
## Email Content
[Email snippet or full body]
## Suggested Actions
- [ ] Reply to sender
- [ ] Forward to accounting
- [ ] Create invoice
- [ ] Archive after processing
## Email Details
- **From:** sender@example.com
- **To:** you@example.com
- **Date:** 2026-03-12 20:23:44
- **Labels:** IMPORTANT, UNREADIntegration with Workflow
Gmail Inbox → Gmail Watcher → /Needs_Action/EMAIL_*.md
↓
Claude processes with /process-vault-tasks
↓
Creates plan or draft reply
↓
Requests approval if needed
↓
Sends reply via Email MCP
↓
Marks as done, logs actionFeatures
Duplicate Prevention
- Tracks processed message IDs in
.processed_emails - Skips already-processed emails
- Persists across restarts
Priority Detection
- Marks emails with IMPORTANT label as high priority
- Detects urgent keywords in subject/body
- Flags time-sensitive requests
Smart Filtering
- Ignores spam and promotional emails
- Focuses on actionable messages
- Respects Gmail's importance signals
Error Handling
- Exponential backoff on API errors
- Graceful handling of network issues
- Continues monitoring after transient failures
Monitoring
Check Status
# View recent activity
tail -f AI_Employee_Vault/Logs/gmail_watcher.log
# Check processed emails count
wc -l .processed_emails
# View created action files
ls -lt AI_Employee_Vault/Needs_Action/EMAIL_*.mdHealth Checks
The watcher logs heartbeat messages every check cycle:
2026-03-12 20:23:44 - GmailWatcher - INFO - Checking for new emails...
2026-03-12 20:23:45 - GmailWatcher - INFO - Found 2 new emails
2026-03-12 20:23:45 - GmailWatcher - INFO - Created EMAIL_client_request_1710275025.mdSecurity
Credential Management
- OAuth2 tokens stored locally
- Never commit
credentials.jsonortoken.json - Tokens auto-refresh when expired
- Scopes limited to read-only access
Privacy
- Email content stays local
- No external logging or analytics
- Processed emails tracked by ID only
- Full audit trail in local logs
Rate Limiting
- Respects Gmail API quotas
- Default: 1 check per 2 minutes
- Exponential backoff on rate limit errors
Troubleshooting
"Invalid credentials" error
# Delete token and re-authenticate
rm token.json
python scripts/gmail_watcher.py"API not enabled" error
- Enable Gmail API in Google Cloud Console
- Wait 1-2 minutes for propagation
- Retry
No emails detected
- Check Gmail query filter
- Verify emails match criteria (unread + important)
- Check
.processed_emailsfor duplicates
Watcher stops running
- Check logs for errors
- Verify network connectivity
- Use process manager (PM2) for auto-restart
Advanced Usage
Custom Email Processing
Extend the watcher for custom logic:
def should_process_email(self, message):
"""Custom filtering logic"""
headers = self.get_headers(message)
subject = headers.get('Subject', '').lower()
# Only process invoices
if 'invoice' not in subject:
return False
# Skip automated emails
if 'noreply' in headers.get('From', ''):
return False
return TrueIntegration with Other Skills
# Chain with processing
python scripts/gmail_watcher.py &
sleep 5
claude /process-vault-tasks
# Scheduled processing
# Add to cron:
# */5 * * * * cd /path/to/Silver && claude /process-vault-tasksPerformance
- Memory: ~50MB per watcher instance
- CPU: Minimal (only during API calls)
- Network: ~1KB per check (no new emails)
- Disk: ~2KB per action file created
Dependencies
google-auth-oauthlib==1.2.0
google-auth-httplib2==0.2.0
google-api-python-client==2.116.0See Also
/process-vault-tasks- Process created action files/send-email- Send email replies via MCPCompany_Handbook.md- Email handling rulesorchestrator.py- Automated scheduling
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

