Meeting Scheduler
Find mutual availability and create Google Calendar events using the
CLI.
Prerequisites
- CLI installed and authenticated
Workflow
1. Resolve attendee email
If the user provides a name but no email, search past calendar events:
bash
gws calendar events list --params '{"calendarId":"primary","q":"<name>","maxResults":10}'
Look at the
array in results to find the matching email. If multiple matches, ask the user to confirm.
2. Detect timezones
Detect each person's timezone by querying
their own calendar directly. When you query a person's calendar via their email as
, the API returns
with that person's local UTC offset — this is the most reliable signal.
bash
gws calendar events list --params '{"calendarId":"<user-email>","maxResults":10}'
gws calendar events list --params '{"calendarId":"<attendee-email>","maxResults":10}'
For each person:
- Look at on non-all-day events (skip events with only )
- Extract the UTC offset (e.g., , ) — this reflects their calendar's timezone
- Tally the most frequent offset to determine their timezone
- Cross-reference with the field on events matching that offset to get the IANA name (e.g., → )
Important: Do NOT rely on
alone — it often reflects the
organizer's or
attendee's timezone rather than the calendar owner's. The
offset from the person's own calendar is the source of truth.
If no timezone can be determined for either person, ask the user.
3. Determine date range
Ask the user for a preferred date range, or default to the next 5 business days.
4. Check free/busy
Query both calendars together. The query range must cover work hours in both timezones:
bash
gws calendar freebusy query --json '{
"timeMin": "<start-RFC3339>",
"timeMax": "<end-RFC3339>",
"items": [{"id": "<user-email>"}, {"id": "<attendee-email>"}]
}'
5. Compute overlapping free slots
- Convert all busy times from UTC to each person's timezone
- Define work hours per person: 9:00-18:00 in their respective timezone
- Find the overlap of both people's work-hour windows, then subtract combined busy blocks
- Filter to slots >= requested meeting duration
- Double-check every slot against BOTH calendars before presenting — do not skip the user's own busy times
- Present slots as a table showing times in both timezones:
Day | User (JST) | Attendee (PST) | Duration
Thu Feb 26 | 15:00 - 16:00 | 22:00 - 23:00 | 1h
If work-hour overlap is very limited (e.g., < 1 hour), note this and suggest the user consider extending hours.
6. Confirm and create the event
Once the user picks a slot, duration, and title:
bash
gws calendar +insert \
--summary "<title>" \
--start "<start-RFC3339>" --end "<end-RFC3339>" \
--attendee "<user-email>" --attendee "<attendee-email>"
For Google Meet links or other advanced options, use the raw API instead:
bash
gws calendar events insert --params '{"calendarId":"primary","conferenceDataVersion":1,"sendUpdates":"all"}' \
--json '{
"summary": "<title>",
"start": {"dateTime": "<start-RFC3339>"},
"end": {"dateTime": "<end-RFC3339>"},
"attendees": [{"email": "<user-email>"}, {"email": "<attendee-email>"}],
"conferenceData": {"createRequest": {"requestId": "<unique-id>", "conferenceSolutionKey": {"type": "hangoutsMeet"}}}
}'
Key notes:
- — repeat for each attendee, always include the user themselves
- param required when adding Meet links
- — notify attendees via email
7. Confirm to user
Show: title, date/time (in both timezones if cross-timezone), attendees, and Meet link.
Important Notes
- Always include the user as an attendee, not just as the calendar owner
- uses for query/path parameters and for request bodies
- Use (or omit, as JSON is default) for reliable parsing
- RFC3339 times must include timezone offset (e.g., for JST)
- The freebusy API returns busy times in UTC — convert carefully
- When computing free slots, verify against both calendars before presenting
- Use helper for simple events; use
gws calendar events insert