Google Calendar Availability Finder

# Google Calendar Availability Finder

Find free time slots in your calendar (and optionally check others' availability), then propose meeting times or generate scheduling suggestions.

## When to Use

- "Find a free slot for a 1-hour meeting this week"
- "When can I meet with Sarah and John next week?"
- "Propose 3 meeting times for a client call"

## Requirements

- **gcalcli** or **Google Cloud CLI** with Calendar API
- OAuth scopes: `calendar.readonly`, `calendar.freebusy`
- `jq` for JSON parsing

## Workflow

### Step 1 — Define Constraints

Collect from user:
- **Duration** — how long is the meeting? (default: 30 min)
- **Date range** — this week, next week, specific dates
- **Working hours** — default 09:00-17:00 (user's timezone)
- **Attendees** — email addresses to check (optional)
- **Preferences** — morning preferred, avoid Fridays, etc.

### Step 2 — Check Your Calendar

```bash
# Fetch your events for the date range
gcalcli agenda "{START_DATE}" "{END_DATE}" --tsv

# Or via API for precise busy/free data
ACCESS_TOKEN=$(gcloud auth print-access-token)

curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timeMin": "{START_ISO}",
    "timeMax": "{END_ISO}",
    "timeZone": "America/New_York",
    "items": [{"id": "primary"}]
  }' \
  "https://www.googleapis.com/calendar/v3/freeBusy" | \
  jq '.calendars.primary.busy'
```

### Step 3 — Check Others' Availability (if attendees provided)

```bash
# FreeBusy query for multiple attendees
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timeMin": "{START_ISO}",
    "timeMax": "{END_ISO}",
    "timeZone": "America/New_York",
    "items": [
      {"id": "primary"},
      {"id": "sarah@company.com"},
      {"id": "john@company.com"}
    ]
  }' \
  "https://www.googleapis.com/calendar/v3/freeBusy" | jq '.calendars'
```

Note: FreeBusy only works for users in the same Google Workspace domain or with shared calendars.

### Step 4 — Calculate Free Slots

Algorithm:
1. Start with all working hours as available
2. Subtract busy blocks from each person's calendar
3. Find intersections where ALL attendees are free
4. Filter by user preferences (morning, avoid Friday, etc.)
5. Sort by proximity (sooner is better) and quality (longer buffer before/after)

### Step 5 — Present Options

```markdown
## Available Meeting Slots (1 hour)

| # | Date | Time | Buffer Before | Buffer After |
|---|------|------|---------------|-------------|
| 1 | Tue, Apr 1 | 10:00 - 11:00 | 30 min | 1 hour |
| 2 | Wed, Apr 2 | 14:00 - 15:00 | 2 hours | 2 hours |
| 3 | Thu, Apr 3 | 09:00 - 10:00 | Start of day | 30 min |

Recommended: **Option 2** — best buffer time around the meeting.
```

### Step 6 — Create Calendar Event

If user picks a slot, create the event (use the Google Calendar Event Creator skill) or offer to draft a scheduling email:

```
"Hi Sarah and John, how does Wednesday Apr 2 at 2pm ET work for a 1-hour sync? If not, I also have Tue 10am or Thu 9am available."
```

## Important Rules

- Respect working hours — never suggest before 9am or after 5pm unless user says so
- Always include timezone in suggestions
- FreeBusy API may not work across orgs — note this limitation
- Suggest 3 options minimum when possible

## Example Prompts

- "Find a 30-minute slot for me and sarah@company.com this week"
- "When am I free for a 2-hour focus block next week?"
- "Propose 3 meeting times for a client call Tue-Thu"