CalendarAgent

Smarty pants agent that sends you an email every week for the things you should care about

Family Calendar Digest Agent — Setup Guide

A Python agent that reads your Google Calendar every week, uses Claude AI to identify what's notable for your family, and emails you a clean HTML digest with sections for Life & Family, Kids, Birthdays, Task Reminders, and Weather.

What You'll Need

• A Google Cloud Platform (GCP) account (free tier works) // You can also run this locally on your machine with locally scheduled cron jobs
• A Gmail account (for sending the digest email)
• An Anthropic API key (for Claude — costs ~$0.04/week)

Step 1: Create a GCP Service Account

1. Go to Google Cloud Console
2. Create a new project (or use an existing one)
3. Enable the Google Calendar API:
   • Go to APIs & Services → Library
   • Search for "Google Calendar API"
   • Click Enable
4. Create a service account:
   • Go to APIs & Services → Credentials
   • Click "Create Credentials" → "Service account"
   • Give it a name (e.g., "calendar-digest")
   • Click Done
5. Create a key for the service account:
   • Click on the service account you just created
   • Go to the "Keys" tab
   • Click "Add Key" → "Create new key" → JSON
   • Save the downloaded JSON file — this is your creds.json
6. Note the service account email (looks like name@project-id.iam.gserviceaccount.com) — you'll need this in Step 3

Step 2: Add Your Claude API Key to creds.json

Open your downloaded creds.json and add this field at the top level:

"claude_api_key": "sk-ant-api03-YOUR_KEY_HERE"

You can get an API key at console.anthropic.com.

Step 3: Share Your Calendars with the Service Account

For each Google Calendar you want the agent to read:

1. Open Google Calendar
2. Click the three dots next to the calendar name → "Settings and sharing"
3. Under "Share with specific people or groups", click "Add people and groups"
4. Paste your service account email from Step 1
5. Set permission to "See all event details"
6. Click Send

To find a calendar's ID:

• For your primary calendar, it's your Gmail address (e.g., you@gmail.com)
• For other calendars, go to Settings → scroll to "Integrate calendar" → copy the Calendar ID

Step 4: Create a Gmail App Password

The agent sends email via Gmail SMTP. You need an App Password (not your regular password):

1. Go to myaccount.google.com/apppasswords
2. You may need to enable 2-Step Verification first
3. Create a new app password (name it "Calendar Digest" or similar)
4. Copy the 16-character password — you'll put this in config.yaml

Step 5: Fill in config.yaml

Copy config.yaml and replace all INSERT_ placeholders:

Field	What to put
creds_path	Full path to your creds.json file
calendar.calendars	Your calendar IDs and labels
email.from_address	Your Gmail address
email.app_password	The App Password from Step 4
email.recipients	Email addresses to receive the digest
weather.latitude/longitude	Your city's coordinates (find at latlong.net)
weather.city_label	Display name (e.g., "San Francisco, CA")
classification.family_context	Describe your family so Claude understands your calendar
classification.routine_patterns	Event name substrings to always skip
classification.notable_patterns	Event name substrings to always surface
logging.log_file	Where to write the log file

Step 6: Install Dependencies

pip install google-api-python-client google-auth anthropic PyYAML

Step 7: Test

python calendar_fam.py --dry-run > test.html && open test.html

This fetches your calendar, classifies events with Claude, and outputs the HTML digest to a file without sending email. Open test.html in your browser to verify it looks right.

Step 8: Send a Real Email

python calendar_fam.py

Check your inbox. If it works, you're ready to schedule it.

Step 9: Schedule Weekly Runs

Option A: Mac (launchd or cron)

Note: Your Mac must be awake for cron to fire. If your Mac sleeps overnight, use Option B.

crontab -e

Add:

0 7 * * 0 cd /path/to/calendar && python3 calendar_fam.py

This runs every Sunday at 7 AM.

Option B: Cloud VM (recommended)

Deploy to a small GCP/AWS VM that's always on:

1. Copy calendar_fam.py, config.yaml, creds.json, and install dependencies
2. Update paths in config.yaml to match the VM
3. Add a cron job:

crontab -e
# Add:
0 6 * * 0 cd /home/youruser/calendar && python3 calendar_fam.py >> /home/youruser/calendar/cron.log 2>&1

Customization Tips

• Add/remove calendars: Edit the calendar.calendars list in config.yaml
• Tune what's routine vs notable: Edit routine_patterns and notable_patterns — these are case-insensitive substring matches against event names
• Change the lookahead window: Edit get_date_range() in calendar_fam.py — change timedelta(days=14) to any number
• Customize the family context: The more detail you provide in family_context, the better Claude will classify your events. Include family member names, roles, recurring appointment contexts, and pet names
• Disable weather: Remove the weather section from config.yaml and the agent will skip it
• Add recipients: Add more email addresses to the recipients list

Cost

• Claude API: ~$0.04/week (Sonnet, ~10K input + 3K output tokens per run)
• Google Calendar API: Free
• Gmail SMTP: Free
• Open-Meteo Weather: Free (no API key needed)

Troubleshooting

Problem	Fix
403: Google Calendar API has not been used	Enable the Calendar API in GCP Console
404: Not Found for a calendar	Share that calendar with your service account email
0 events from a calendar	Verify the calendar ID is correct and the calendar has events in the next 14 days
Email not sending	Check your Gmail App Password and that "Less secure apps" / 2FA is set up correctly
FileNotFoundError for log	Make sure the directory for log_file exists