agentleFS
muhammad-anas35muhammad-anas35/Nexus-ai-employee/skills/email/gmail_watcher/SKILL.md

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

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
  1. Distinctive:

    Create a new project or select existing

    line 44
  2. Distinctive:

    Place in project root

    line 48
  3. Very specific:

    Never commit credentials.json or token.json

    line 188
  4. Distinctive:

    No external logging or analytics

    line 194
  5. Distinctive:

    Default: 1 check per 2 minutes

    line 200
  6. Distinctive:

    Wait 1-2 minutes for propagation

    line 214
  7. Distinctive:

    Check Gmail query filter

    line 218
  8. Distinctive:

    Verify emails match criteria (unread + important)

    line 219
  9. Very specific:

    Check .processed_emails for duplicates

    line 220
  10. Distinctive:

    Check logs for errors

    line 223
  11. Distinctive:

    Use process manager (PM2) for auto-restart

    line 225

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 300

What It Does

  1. Monitors Gmail using Gmail API every 2 minutes (configurable)
  2. Filters for unread and important emails
  3. Creates action files in /Needs_Action/EMAIL_*.md
  4. Tracks processed emails to avoid duplicates
  5. Logs all activity to /Logs/gmail_watcher.log

Prerequisites

Gmail API Setup

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable Gmail API
  4. Create OAuth 2.0 credentials
  5. Download credentials as credentials.json
  6. 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 it

Configuration

Environment Variables

# .env file
GMAIL_CREDENTIALS_PATH=./credentials.json
GMAIL_TOKEN_PATH=./token.json
VAULT_PATH=./AI_Employee_Vault
CHECK_INTERVAL=120  # seconds

Gmail 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, UNREAD

Integration 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 action

Features

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_*.md

Health 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.md

Security

Credential Management

  • OAuth2 tokens stored locally
  • Never commit credentials.json or token.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_emails for 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 True

Integration 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-tasks

Performance

  • 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.0

See Also

  • /process-vault-tasks - Process created action files
  • /send-email - Send email replies via MCP
  • Company_Handbook.md - Email handling rules
  • orchestrator.py - Automated scheduling

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.