google-calendar

name	google-calendar
description	Manage your Google Calendar from Claude Code. Create events with Meet links, send invites, check availability.
allowed-tools	Bash(CLAUDECLAW_DIR=* ~/.venv/bin/python3 ~/.config/calendar/gcal.py *)

Google Calendar Skill

Purpose

Create meetings with Google Meet links, send invites, check availability, and manage calendar events from Claude Code.

Environment

The calendar CLI reads credential paths from environment variables, loaded from ClaudeClaw's .env via CLAUDECLAW_DIR. Every command MUST use this prefix:

CLAUDECLAW_DIR=/path/to/claudeclaw

Your .env should contain:

GOOGLE_CREDS_PATH=~/.config/gmail/credentials.json
GCAL_TOKEN_PATH=~/.config/calendar/token.json

If these aren't set, the script falls back to ~/.config/gmail/credentials.json (shared with Gmail) and ~/.config/calendar/token.json.

Commands

List upcoming events

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py list

Returns next 10 events as JSON. Each entry has: id, summary, start, end, attendees, meet_link.

List events within N days

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py list --days 7

Get event details

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py get <event_id>

Create event with Meet link and invites

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py create "Meeting Title" "2026-03-15 10:00" --duration 30 --attendees "[e-mail],[e-mail]" --meet

• --duration in minutes (default: 30)
• --attendees comma-separated emails (sends invite emails automatically)
• --meet adds a Google Meet video link
• --description adds event description
• --location adds location

Update an event

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py update <event_id> --title "New Title" --start "2026-03-16 14:00" --duration 60 --add-attendees "[e-mail]" --meet

All flags are optional. Only provided fields are updated. Attendees are notified of changes.

Cancel an event

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py cancel <event_id>

Cancels the event and sends cancellation notices to all attendees.

Check free/busy

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py freebusy "2026-03-15 09:00" "2026-03-15 17:00"

Shows busy time slots in the given range. If no conflicts, says "Time range is free."

Re-authenticate

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py auth

CRITICAL: Day-of-Week Verification

NEVER assume a date from a day name (e.g. "Monday", "next Thursday"). Always verify before creating an event:

python3 -c "from datetime import date; d = date(2026, 3, 15); print(f'{d.strftime(\"%A\")} {d}')"

• If the output day name does NOT match what was requested, find the correct date
• This is a blocking requirement. Getting the day wrong sends a wrong invite to a real person.

Workflow

1. If the user doesn't specify a time, check the calendar first with list --days 7
2. If a day name was mentioned, verify the date matches that day
3. Check freebusy for the proposed slot
4. Create the event with --meet and --attendees
5. Confirm: show title, time, day of week, attendees, and Meet link

Confirmation Before Creating

Always show the user what you're about to create before running the command:

• Title
• Day of week + Date/time (e.g. "Monday Mar 15, 12:00pm")
• Duration
• Attendees
• Meet: yes/no

Then ask for confirmation before executing.

Datetime Formats

All of these work:

• 2026-03-15 10:00
• 2026-03-15 2:00PM
• 2026-03-15T14:00
• 03/15/2026 10:00

Timezone

The script defaults to America/New_York. To change it, edit the TIMEZONE constant in gcal.py.

Defaults

• Duration: 30 minutes (unless the user specifies otherwise)
• Always add --meet unless the user specifically says no video call
• Invites are sent to all attendees automatically

One-Time Setup

Uses the same Google Cloud project as Gmail. If token.json is missing:

CLAUDECLAW_DIR=/path/to/claudeclaw ~/.venv/bin/python3 ~/.config/calendar/gcal.py auth

Browser opens, sign in, approve Calendar access, done.

If you haven't set up Gmail yet, you'll need credentials.json first. See the Gmail skill setup instructions.

Error Handling

• If credentials.json missing, point to Gmail setup (same file)
• If token.json missing, run auth automatically
• If event creation fails, show error and ask the user what to do