google-calendar-sync

Google Calendar Sync

Comprehensive Google Calendar integration enabling event management, calendar organization, availability checking, recurring event handling, and workflow automation through the Google Calendar API v3.

Quick Start

When asked to work with Google Calendar:

1. Authenticate: Set up OAuth2 credentials (one-time setup)
2. List events: View upcoming events and meetings
3. Create events: Schedule new meetings and appointments
4. Update events: Modify existing events
5. Check availability: Find free time slots
6. Manage calendars: Work with multiple calendars

Prerequisites

One-Time Setup

1. Enable Calendar API:

# Visit Google Cloud Console
# https://console.cloud.google.com/

# Enable Calendar API for your project
# APIs & Services > Enable APIs and Services > Google Calendar API

2. Create OAuth2 Credentials:

# In Google Cloud Console:
# APIs & Services > Credentials > Create Credentials > OAuth client ID
# Application type: Desktop app
# Download credentials as credentials.json

3. Install Dependencies:

pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client python-dateutil pytz --break-system-packages

4. Initial Authentication:

python scripts/authenticate.py
# Opens browser for Google sign-in
# Saves token.json for future use

See reference/setup-guide.md for detailed setup.

Core Operations

List Events

View upcoming events:

# Today's events
python scripts/list_events.py --today

# This week
python scripts/list_events.py --days 7

# Specific date range
python scripts/list_events.py \
  --start 2025-01-01 \
  --end 2025-01-31

# Next N events
python scripts/list_events.py --limit 10

Filter events:

# By search term
python scripts/list_events.py --query "team meeting"

# By calendar
python scripts/list_events.py --calendar "Work"

# Only free/busy
python scripts/list_events.py --show-deleted false

Get event details:

# Get specific event
python scripts/get_event.py --event-id EVENT_ID

# Export to file
python scripts/get_event.py --event-id EVENT_ID --output event.json

Create Events

Simple event:

# Basic event
python scripts/create_event.py \
  --summary "Team Meeting" \
  --start "2025-01-20 14:00" \
  --end "2025-01-20 15:00"

# With description
python scripts/create_event.py \
  --summary "Project Review" \
  --start "2025-01-21 10:00" \
  --end "2025-01-21 11:00" \
  --description "Q4 project review meeting"

# With location
python scripts/create_event.py \
  --summary "Client Meeting" \
  --start "2025-01-22 14:00" \
  --end "2025-01-22 15:00" \
  --location "Conference Room A"

All-day event:

python scripts/create_event.py \
  --summary "Conference" \
  --start "2025-02-15" \
  --end "2025-02-17" \
  --all-day

With attendees:

python scripts/create_event.py \
  --summary "Team Standup" \
  --start "2025-01-20 09:00" \
  --duration 30 \
  --attendees "[email protected],[email protected]" \
  --send-notifications

With reminders:

python scripts/create_event.py \
  --summary "Important Meeting" \
  --start "2025-01-20 14:00" \
  --duration 60 \
  --reminders "popup:10,email:60"  # 10 min popup, 60 min email

Video conference:

# Add Google Meet link
python scripts/create_event.py \
  --summary "Virtual Meeting" \
  --start "2025-01-20 14:00" \
  --duration 60 \
  --add-meet-link

Recurring Events

Create recurring:

# Daily standup
python scripts/create_recurring.py \
  --summary "Daily Standup" \
  --start "2025-01-20 09:00" \
  --duration 15 \
  --rule "FREQ=DAILY;COUNT=30"

# Weekly meeting
python scripts/create_recurring.py \
  --summary "Team Meeting" \
  --start "2025-01-20 14:00" \
  --duration 60 \
  --rule "FREQ=WEEKLY;BYDAY=MO,WE,FR;UNTIL=20251231"

# Monthly review
python scripts/create_recurring.py \
  --summary "Monthly Review" \
  --start "2025-01-15 10:00" \
  --duration 120 \
  --rule "FREQ=MONTHLY;BYMONTHDAY=15"

Recurrence rule examples:

# Every weekday
"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR"

# Every Monday and Wednesday
"FREQ=WEEKLY;BYDAY=MO,WE"

# First Monday of every month
"FREQ=MONTHLY;BYDAY=1MO"

# Every 2 weeks
"FREQ=WEEKLY;INTERVAL=2"

# Until specific date
"FREQ=DAILY;UNTIL=20251231T235959Z"

# Specific number of occurrences
"FREQ=WEEKLY;COUNT=10"

See reference/recurrence-rules.md for complete RRULE syntax.

Update Events

Modify event:

# Update time
python scripts/update_event.py \
  --event-id EVENT_ID \
  --start "2025-01-20 15:00" \
  --end "2025-01-20 16:00"

# Update summary and description
python scripts/update_event.py \
  --event-id EVENT_ID \
  --summary "Updated Meeting Title" \
  --description "New description"

# Add attendees
python scripts/update_event.py \
  --event-id EVENT_ID \
  --add-attendees "[email protected]"

# Move to different calendar
python scripts/move_event.py \
  --event-id EVENT_ID \
  --destination-calendar "Personal"

Update recurring instance:

# Update single instance
python scripts/update_event.py \
  --event-id EVENT_ID \
  --instance-date "2025-01-20" \
  --start "2025-01-20 16:00"

# Update all future instances
python scripts/update_event.py \
  --event-id EVENT_ID \
  --start "2025-01-20 16:00" \
  --update-following

Delete Events

Delete event:

# Delete single event
python scripts/delete_event.py --event-id EVENT_ID

# Delete recurring instance
python scripts/delete_event.py \
  --event-id EVENT_ID \
  --instance-date "2025-01-20"

# Delete all future instances
python scripts/delete_event.py \
  --event-id EVENT_ID \
  --delete-following

Check Availability

Find free time:

# Check availability
python scripts/check_availability.py \
  --start "2025-01-20 09:00" \
  --end "2025-01-20 17:00" \
  --duration 60

# Check multiple calendars
python scripts/check_availability.py \
  --calendars "Work,Personal" \
  --date "2025-01-20" \
  --duration 30

# Find next available slot
python scripts/find_next_slot.py \
  --duration 60 \
  --business-hours-only

FreeBusy query:

# Check if people are free
python scripts/check_freebusy.py \
  --emails "[email protected],[email protected]" \
  --start "2025-01-20 14:00" \
  --end "2025-01-20 15:00"

Calendar Management

List calendars:

# Get all calendars
python scripts/list_calendars.py

# Get calendar details
python scripts/get_calendar.py --calendar-id "primary"

Create calendar:

# Create new calendar
python scripts/create_calendar.py \
  --summary "Project Alpha" \
  --description "Project Alpha team calendar" \
  --timezone "America/New_York"

Share calendar:

# Share with user
python scripts/share_calendar.py \
  --calendar-id CALENDAR_ID \
  --email "[email protected]" \
  --role writer

# Make public
python scripts/share_calendar.py \
  --calendar-id CALENDAR_ID \
  --public \
  --role reader

Calendar roles:

• owner - Full control
• writer - Create/modify events
• reader - View only
• freeBusyReader - See free/busy only

Common Workflows

Workflow 1: Schedule Meeting with Attendees

Scenario: Find time and schedule meeting

# 1. Check availability
python scripts/check_freebusy.py \
  --emails "[email protected],[email protected]" \
  --date "2025-01-20" \
  --duration 60

# 2. Create meeting
python scripts/create_event.py \
  --summary "Project Discussion" \
  --start "2025-01-20 14:00" \
  --duration 60 \
  --attendees "[email protected],[email protected]" \
  --add-meet-link \
  --send-notifications

Workflow 2: Sync with Local Calendar

Scenario: Export/import events

# Export to ICS
python scripts/export_calendar.py \
  --calendar-id "primary" \
  --output calendar.ics \
  --start "2025-01-01" \
  --end "2025-12-31"

# Import from ICS
python scripts/import_calendar.py \
  --file events.ics \
  --calendar-id "primary"

Workflow 3: Daily Schedule Summary

Scenario: Get morning email with day's schedule

# Generate daily summary
python scripts/daily_summary.py \
  --send-email \
  --to "[email protected]"

Workflow 4: Recurring Task Events

Scenario: Create recurring reminders

# Create recurring task
python scripts/create_recurring.py \
  --summary "Submit Weekly Report" \
  --start "2025-01-20 16:00" \
  --duration 30 \
  --rule "FREQ=WEEKLY;BYDAY=FR" \
  --reminders "popup:0"

Workflow 5: Event Analytics

Scenario: Analyze calendar usage

# Generate statistics
python scripts/calendar_stats.py \
  --start "2025-01-01" \
  --end "2025-01-31" \
  --output stats.json

# Meeting time analysis
python scripts/meeting_analysis.py --days 30

Event Colors

Color IDs:

COLORS = {
    '1': 'Lavender',
    '2': 'Sage',
    '3': 'Grape',
    '4': 'Flamingo',
    '5': 'Banana',
    '6': 'Tangerine',
    '7': 'Peacock',
    '8': 'Graphite',
    '9': 'Blueberry',
    '10': 'Basil',
    '11': 'Tomato'
}

Set event color:

python scripts/update_event.py \
  --event-id EVENT_ID \
  --color-id 9  # Blueberry

Reminder Options

Reminder methods:

• popup - In-app notification
• email - Email reminder

Reminder timing:

# Minutes before event
reminders = [
    {'method': 'popup', 'minutes': 10},
    {'method': 'email', 'minutes': 60},
    {'method': 'popup', 'minutes': 1440}  # 1 day
]

Use default reminders:

# Use calendar's default reminders
'useDefault': True

Time Zones

Specify timezone:

# Event in specific timezone
python scripts/create_event.py \
  --summary "Meeting" \
  --start "2025-01-20 14:00" \
  --timezone "America/Los_Angeles" \
  --duration 60

Common timezones:

'Am

---

*Content truncated.*