Google Calendar

---
name: google-calendar
description: View Google Calendar events for any day, create and manage events, and check availability
compatibility: "Designed for Vellum personal assistants"
metadata:
  icon: assets/icon.svg
  emoji: "📅"
  vellum:
    category: "calendar"
    display-name: "Google Calendar"
    user-invocable: true
    activation-hints:
      - "plan my day or my week"
      - "what does my day look like"
      - "check my availability, find open time slots, when am I free"
---

## Script Reference

All operations use a single CLI script that returns JSON:

- **Success**: `{ "ok": true, "data": ... }`
- **Failure**: `{ "ok": false, "error": "..." }`

| Script            | Subcommand     | Description                                                    |
| ----------------- | -------------- | -------------------------------------------------------------- |
| `scripts/gcal.ts` | `list`         | List events within a date range                                |
| `scripts/gcal.ts` | `get`          | Get full details of a specific event                           |
| `scripts/gcal.ts` | `create`       | Create a new event (**requires user confirmation**)            |
| `scripts/gcal.ts` | `availability` | Check free/busy times across calendars                         |
| `scripts/gcal.ts` | `rsvp`         | Respond to an event invitation (accepted, declined, tentative) |

## Usage Examples

```bash
# List events in a date range
bun scripts/gcal.ts list --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-22T00:00:00Z"

# Get full details of a specific event
bun scripts/gcal.ts get --event-id "abc123"

# Create a new event (gates on assistant ui confirm)
bun scripts/gcal.ts create --summary "Team Meeting" --start "2024-01-15T09:00:00-05:00" --end "2024-01-15T10:00:00-05:00" --timezone "America/New_York"

# Check availability for a day
bun scripts/gcal.ts availability --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-15T23:59:59Z"

# RSVP to an event invitation
bun scripts/gcal.ts rsvp --event-id "abc123" --response accepted

# Target a specific connected account (see "Multiple Accounts" below)
bun scripts/gcal.ts list --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-22T00:00:00Z" --account "work@example.com"
```

Every subcommand accepts `--account <email>` to select which connected Google account the request runs against. When omitted, the request runs against a single account chosen automatically — safe only when exactly one Google account is connected. Each JSON envelope echoes the queried account in an `account` field when it is reported by the OAuth layer, so an empty result is self-describing (e.g. `No events found in the specified time range for work@example.com.`).

## Connection Setup

1. **Check connection health first.** Run `assistant oauth status google`. This checks whether the user's Google account is connected and the token is valid. Google Calendar shares the same OAuth connection as Gmail — if the user already connected Gmail, calendar access is included.
   - **If the status output shows more than one active connection, you MUST pass `--account <email>` on every `scripts/gcal.ts` invocation**, matching the calendar the user is asking about. When the user references a calendar by name or company (e.g. "my Acme calendar"), map it to the connected account email before querying. **Omitting `--account` with multiple connections silently queries one arbitrary account** — an empty or partial result then looks like a genuinely free calendar when it is really the wrong account. Confirm the `account` field in each response matches the account you intended.
2. **If no connection is found or the status check fails:** Load the `vellum-oauth-integrations` skill. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.

## Scheduling Playbook

When the user wants to schedule something:

1. **Always check availability first** before proposing times. Use `bun scripts/gcal.ts availability` to find free slots.
2. Propose 2-3 available time options to the user.
3. Once the user picks a time, create the event with `bun scripts/gcal.ts create`.
4. If adding other attendees, mention that they'll receive an invitation email.

## Date & Time Handling

- Use ISO 8601 format for dates and times (e.g., `2024-01-15T09:00:00-05:00`).
- For all-day events, use date-only format (e.g., `2024-01-15`).
- Always ask the user for their timezone if it's not already known from context or their profile.
- When listing events, display times in the user's local timezone.

## Confidence & Safety

Create and RSVP are **medium-risk** operations:

- **Create**: The `create` subcommand gates on `assistant ui confirm` — it presents a confirmation dialog to the user and only proceeds if approved. Pass `--skip-confirm` when the user has already given explicit confirmation in the conversation.
- **RSVP**: The `rsvp` subcommand gates on `assistant ui confirm` — it presents a confirmation dialog showing the event, current status, and new response. Pass `--skip-confirm` when the user has already given explicit confirmation in the conversation.

## Error Recovery

When a calendar script fails with a token or authorization error:

1. **Try to reconnect silently.** Run `assistant oauth ping google`. This often resolves expired tokens automatically.
2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Google Calendar needs to be reconnected - let me set that up") and immediately load the `vellum-oauth-integrations` skill. The user came to you to get something done, not to troubleshoot - make it seamless.
3. **Never try alternative approaches.** Don't use curl, browser automation, or any workaround. If the scripts can't do it, the reconnection flow is the answer.
4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.