git:20260707.0c1990a to git:20260810.33e6f3f

---

name: google-calendar

compatibility: "Designed for Vellum personal assistants"

metadata:

icon: assets/icon.svg

emoji: "📅"

vellum:

category: "calendar"

display-name: "Google Calendar"

user-invocable: true

activation-hints:

---

## 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.

Confidence scores for medium-risk operations:

- **0.9-1.0**: User explicitly requested this exact action

- **0.7-0.8**: Action is strongly implied by context

- **0.5-0.6**: Reasonable inference but some ambiguity

- **Below 0.5**: Ask the user to confirm before proceeding

## 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.