google-calendar-sync

What this skill does

# 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:**
```bash
# 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:**
```bash
# In Google Cloud Console:
# APIs & Services > Credentials > Create Credentials > OAuth client ID
# Application type: Desktop app
# Download credentials as credentials.json
```

**3. Install Dependencies:**
```bash
pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client python-dateutil pytz --break-system-packages
```

**4. Initial Authentication:**
```bash
python scripts/authenticate.py
# Opens browser for Google sign-in
# Saves token.json for future use
```

See [reference/setup-guide.md](reference/setup-guide.md) for detailed setup.

## Core Operations

### List Events

**View upcoming events:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
python scripts/create_event.py \
  --summary "Conference" \
  --start "2025-02-15" \
  --end "2025-02-17" \
  --all-day
```

**With attendees:**
```bash
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:**
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```python
# 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](reference/recurrence-rules.md) for complete RRULE syntax.

### Update Events

**Modify event:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Get all calendars
python scripts/list_calendars.py

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

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

**Share calendar:**
```bash
# 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

```bash
# 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

```bash
# Export to ICS
python scripts/export_calendar.py \
  --calendar-id "primary" \
  --output calendar.ic