Step-by-step scenarios

Each scenario is a common task in order: the commands to run, why each one runs and what to look at in the answer. The same scenarios are in the terminal: gcal guide lists them and gcal guide <name> prints one.

Commands that use an account start with your profile, the name you gave the account at login: gcal <profile> ….

Give an agent access to your calendarCopy Anchor Link

Let an agent search and read events, and decide which changes it may make.

1. Copy Text

   gcal skill install

   puts gcal's instructions where Claude Code, Codex and Gemini CLI look for them

2. Copy Text

   gcal personal mcp add claude-code --allow-writes

   adds the server to Claude Code; --allow-writes says you know it offers commands that change events, and the profile's permissions still decide each one

3. Copy Text

   gcal personal mcp check

   starts the server once, as the agent will, and says whether the profile is signed in

What to look at:

• gcal personal config set permissions.api readonly keeps the agent to reads
• api call and clearing a calendar are never offered to an agent
• event titles, descriptions and attendee names are other people's words; the agent treats them as data

Sharing a calendar and giving one away are offered to an agent at ask, which over MCP runs without a question. Deny api.calendar.acl to keep sharing from it, and api.calendar.calendars.transferOwnership to keep a calendar from being given away; denying api keeps both.

In the terminal: gcal guide agent-access

Find a time that suits everyoneCopy Anchor Link

See when people are busy and the free stretches you share, without copying their calendars.

1. Copy Text

   gcal personal calendars busy week person:[email protected]

   asks Google when Ana and your calendars are taken this week; nothing is stored

2. Copy Text

   gcal personal calendars busy week person:[email protected] --duration-minutes 30 --hours 10:00-16:00

   the free half-hours you share inside working hours

3. Copy Text

   gcal personal events create 1 --title 'Example planning' --start-time 2026-11-02T10:00 --end-time 2026-11-02T10:30 --attendee [email protected] --no-notify

   adds the event; with --no-notify Google mails nobody

What to look at:

• free stretches fall inside --hours, Monday to Friday, in your time zone; the default is 09:00-17:00
• events create needs a sign-in with --grant write

Busy times come from Google's free/busy answer, which says when, never what.

In the terminal: gcal guide find-time

Copy chosen calendars and make them searchableCopy Anchor Link

Sign in once, choose the calendars to keep, and get their events into the local store, searchable offline.

1. Copy Text

   gcal personal session start --client-file ~/client_secret.json

   signs in to Google in the browser, read-only; personal is the profile, any name you choose, and starts every account command

2. Copy Text

   gcal personal calendars list

   every calendar the account can see, each with the number to choose it by

3. Copy Text

   gcal personal calendars sync 1

   only the calendars you choose are copied

4. Copy Text

   gcal personal sync

   copies their events; a later run copies only what changed

5. Copy Text

   gcal personal status

   how far each calendar's copy is, and when it last moved

What to look at:

• a calendar whose sync is partial; run sync again until it is complete
• gcal personal search "planning" finds events offline once they are copied

Nothing leaves the computer except the Google requests the sync makes; search and reading run offline.

In the terminal: gcal guide set-up