pi-agent-google-calendar-tool

Pi package that adds Google Calendar tools powered by Google Calendar API v3 and OAuth device-code login. It supports multiple Google accounts, calendar discovery, reading/searching events, creating/updating/deleting events, reminders, recurrence, attendees, Google Meet links, quick-add, free/busy checks, and calendar settings.

Install

pi install ./PI-Google-Calendar

Local development test:

cd PI-Google-Calendar
npm install
npm run typecheck
npm test
pi -e ./

Google OAuth setup (current Google Auth Platform UI)

This extension logs in with Google's OAuth 2.0 Device Authorization flow. In the current Google Cloud UI, most OAuth setup is under Google Auth Platform rather than the older APIs & Services → OAuth consent screen page.

You only need to create the Google Cloud OAuth client once. After that, run /google-calendar-login inside Pi for each Google account you want to connect.

1. Select or create a Google Cloud project

1. Open https://console.cloud.google.com/.
2. Use the project selector in the top bar.
3. Select an existing project or create a new one.
4. Keep this same project selected for all steps below.

2. Enable Google Calendar API

1. Open APIs & Services → Library.
2. Search for Google Calendar API.
3. Open it and click Enable.

Direct URL, if you already have the right project selected:

https://console.cloud.google.com/apis/library/calendar-json.googleapis.com

3. Configure Google Auth Platform

1. Open Google Auth Platform:

https://console.cloud.google.com/auth/overview

2. If Google shows Get started, complete the app registration:
   • App name: for example Pi Google Calendar.
   • User support email: your email.
   • Audience:
     • Internal for Google Workspace-only usage.
     • External for personal Gmail accounts or mixed users.
   • Contact information: your email.
3. Open Branding and complete any required fields.
4. Open Audience:
   • If the app is External and in Testing, add every Google account that will use /google-calendar-login under Test users.
   • If you do not add the account, Google may reject login with access_denied or an unverified/testing-app message.
5. Open Data Access and add/confirm the scopes used by the extension:

[
  "openid",
  "email",
  "profile",
  "https://www.googleapis.com/auth/calendar"
]

What the scopes are for:

• openid, email, profile: let the extension discover the email address of the account that completed login.
• https://www.googleapis.com/auth/calendar: allows normal Google Calendar read/write operations: list calendars, list/search events, create/update/delete events, attendees, reminders, recurrence, Google Meet links, and free/busy checks.

4. Create the OAuth client

1. Open Google Auth Platform → Clients:

https://console.cloud.google.com/auth/clients

2. Click Create client.
3. For Application type, choose:

TVs and Limited Input devices

4. Name it, for example Pi Google Calendar Device Client.
5. Click Create.
6. Copy the Client ID.
7. If Google also shows a Client secret, copy it too. It may only be shown/downloadable at creation time.

Important:

• Do not create a Web application OAuth client for this extension.
• You do not need redirect URIs for the TVs and Limited Input devices client type.
• If /google-calendar-login returns invalid_client, the most common causes are a wrong client type, wrong client ID, missing client secret when Google requires one, or using a client from a different project than the enabled Calendar API.

5. Add the OAuth client to Pi

The package creates this config file on install/startup:

~/.pi/agent/pi-google-calendar/config.json

On Windows this is usually:

C:\Users\<your-user>\.pi\agent\pi-google-calendar\config.json

Edit it and set clientId. Set clientSecret only if Google gave you one:

{
  "clientId": "1234567890-abcdef.apps.googleusercontent.com",
  "clientSecret": "OPTIONAL_CLIENT_SECRET_OR_EMPTY_STRING",
  "scopes": ["openid", "email", "profile", "https://www.googleapis.com/auth/calendar"],
  "maxDescriptionChars": 12000,
  "defaultCalendarId": "primary",
  "timeZone": "Europe/Madrid"
}

If you do not have a client secret, omit clientSecret or leave it empty.

6. Run device-code login

Start Pi with the extension loaded, then run:

/google-calendar-login

Pi will show something like:

Open: https://www.google.com/device
Code: ABCD-EFGH

Open the URL in a browser, enter the code exactly as shown, choose your Google account, and approve access.

After login, refresh tokens are stored locally in:

~/.pi/agent/pi-google-calendar/accounts.json

Verify with:

/google-calendar-status

Then you can ask Pi things like:

List my calendars
What meetings do I have tomorrow?
Create an event tomorrow at 10:00 called Dentist

Troubleshooting current Google OAuth setup

• invalid_client: create a new client under Google Auth Platform → Clients with type TVs and Limited Input devices. Check clientId, and add clientSecret if Google provided/requires it.
• access_denied: if the app is External and Testing, add your Google account under Audience → Test users.
• Calendar API errors after login: enable Google Calendar API in the same project that owns the OAuth client.
• Google says the app is not verified: keep the app in Testing and add test users, or complete Google's verification process for broader external use.
• Changed scopes: run /google-calendar-login again after changing scopes so Google can grant the new permissions.
• Wrong account: run /google-calendar-status, /google-calendar-set-default <email>, or /google-calendar-logout <email> and log in again.

Configuration

On install/startup the package creates:

~/.pi/agent/pi-google-calendar/config.json

{
  "clientId": "YOUR_GOOGLE_OAUTH_CLIENT_ID.apps.googleusercontent.com",
  "clientSecret": "",
  "scopes": ["openid", "email", "profile", "https://www.googleapis.com/auth/calendar"],
  "maxDescriptionChars": 12000,
  "defaultCalendarId": "primary",
  "timeZone": "Europe/Madrid"
}

~/.pi/agent/pi-google-calendar/accounts.json stores OAuth refresh tokens and is written with restrictive file permissions where supported.

Only ~/.pi/agent/pi-google-calendar/config.json and ~/.pi/agent/pi-google-calendar/accounts.json are used in this development version. Custom paths, project-local config files, package-local config files, legacy paths, migrations, and environment overrides are not supported.

Login

/google-calendar-login

Pi shows a Google device-code URL and code. Complete browser login; refresh tokens are stored under the Google account email.

Account commands:

• /google-calendar-status — show config and login state.
• /google-calendar-set-default <email> — set default account.
• /google-calendar-logout [email] — remove stored tokens for one account.

Tools

• google_calendar_list_calendars — list calendar names and IDs.
• google_calendar_list_events — list/search events; returns refs like e1.
• google_calendar_event — one compact tool for action=get|create|update|delete|quickAdd.
• google_calendar_freebusy — check availability across calendars.

Use refs from google_calendar_list_events with google_calendar_event for get/update/delete.

Reminder example

{
  "summary": "Dentist",
  "start": "2026-06-01T09:00:00+02:00",
  "end": "2026-06-01T10:00:00+02:00",
  "reminders": {
    "useDefault": false,
    "overrides": [
      { "method": "popup", "minutes": 30 },
      { "method": "email", "minutes": 1440 }
    ]
  }
}

For all-day events, Google Calendar uses an exclusive end date: one day on 2026-06-01 is start=2026-06-01, end=2026-06-02.