Google Calendar — Calendar Plugin

Google Calendar — Calendar Plugin

Auth: OAuth2 via Google Calendar API URL: https://calendar.google.com Configuration: Set credentials and calendar IDs in vault/calendar/config.md

What It Does

Provides the calendar-agent with live event data across all configured calendars. This is the primary input for focus time analysis — the agent reads the actual schedule to calculate how many qualifying deep-work blocks (90+ continuous minutes) occurred in the past week and are available in the upcoming week. It also supports writing focus block events and deadline reminder events directly to the calendar as part of the weekly agenda flow.

Data Available

• Events in a date range across multiple calendars (title, start time, end time, description, location, attendees)
• Free/busy windows for scheduling focus blocks — identify gaps 90+ minutes long with no events
• Event recurrence information (weekly standups, monthly reviews, recurring commitments)
• All-day events (holidays, deadlines, OOO blocks)
• Multi-calendar aggregation: personal + work + shared calendars merged into one timeline view
• Event creation: create single or recurring events with title, time, description, and color
• Event update and deletion: modify or remove events created by the agent

Configuration

Add to vault/calendar/config.md:

gcal_credentials: ~/Documents/aireadylife/vault/calendar/00_current/gcal-oauth.json
gcal_primary_calendar_id: [email protected]
gcal_work_calendar_id: [email protected]
gcal_focus_calendar_id: [email protected]   # calendar where focus blocks are written
gcal_color_focus: 9        # Blueberry — used for focus block events
gcal_color_deadline: 11    # Tomato — used for deadline reminder events

OAuth2 setup: Create a project in Google Cloud Console → enable Google Calendar API → create OAuth2 credentials → download JSON to vault/calendar/00_current/gcal-oauth.json. Scope needed: https://www.googleapis.com/auth/calendar (full read/write).

Key API

GET  https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
     ?timeMin={RFC3339}&timeMax={RFC3339}&singleEvents=true&orderBy=startTime
     &fields=items(id,summary,start,end,description,location,attendees,recurrence,colorId)
POST https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
     Body: {summary, start: {dateTime, timeZone}, end: {dateTime, timeZone}, description, colorId}
GET  https://www.googleapis.com/calendar/v3/freeBusy
     Body: {timeMin, timeMax, items: [{id: calendarId}]}
PATCH https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events/{eventId}
DELETE https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events/{eventId}
Authorization: Bearer {oauth_token}

Focus Time Analysis

When running focus time analysis (flow-analyze-focus-time), read events from all configured calendars merged and sorted by start time. For each day:

1. Build a timeline of all events (start, end, duration, type)
2. Identify gaps of 90+ minutes with no scheduled events — these are qualifying focus windows
3. For each qualifying gap that falls within working hours (configurable; default 8am–6pm), count it as a focus block opportunity. If the day's calendar shows a gap was available but the agent cannot confirm it was used for deep work, note it as "available" (not "used")
4. Confirmed focus blocks come from: (a) events titled "Focus Time", "Deep Work", or similar that the agent or user created, or (b) user-reported focus time logged to the vault

Event Classification

Classify each event by type to support focus time and schedule quality analysis:

• Meeting: 2+ attendees, or title contains "meeting / call / sync / standup / 1:1 / interview"
• Focus block: Created by calendar-agent, or title contains "focus / deep work / writing / coding"
• Admin: Title contains "review / plan / prep / admin / email" — 1 person, ≤30 minutes
• Personal: On personal calendar, or title contains "appt / doctor / gym / lunch / travel"
• All-day / deadline: All-day event — treated as a deadline marker or OOO day

Focus Block Event Creation

When creating focus blocks as part of weekly agenda:

• Title: Focus: {topic or domain} — e.g., "Focus: Project work" or "Focus: Deep work"
• Color: Blueberry (colorId: 9) — visually distinct from meetings
• Description: Include the vault open-loop or OKR it addresses if known
• Duration: Minimum 90 minutes; prefer 2-3 hour blocks
• Placement: Mornings preferred (before 12pm) — protect from afternoon meeting creep
• Do not create focus blocks that overlap with existing events

Used By

• op-weekly-agenda — read next 7 days of events across all calendars; create focus block events; write agenda to vault
• op-focus-time-review — read past 7 days of events to calculate qualifying focus blocks; compare against 8-hour weekly target
• op-deadline-planning — create deadline reminder events on the calendar for hard deadlines flagged in the vault
• flow-analyze-focus-time — merge multi-calendar event data for focus time calculation
• flow-build-agenda — use free/busy data to place focus blocks in the weekly schedule

Vault Output

~/Documents/aireadylife/vault/calendar/00_current/ — event summaries written after weekly reads ~/Documents/aireadylife/vault/calendar/00_current/ — focus time audit records written by focus-time-review