gcal-pro

Manage Google Calendar through natural conversation.

Quick Reference

Action

Command

Tier

View today	python scripts/gcal_core.py today	Free
View tomorrow	python scripts/gcal_core.py tomorrow	Free
View week	python scripts/gcal_core.py week	Free
Search events	python scripts/gcal_core.py search -q "meeting"	Free
List calendars	python scripts/gcal_core.py calendars	Free
Find free time	python scripts/gcal_core.py free	Free
Quick add	python scripts/gcal_core.py quick -q "Lunch Friday noon"	Pro
Delete event	python scripts/gcal_core.py delete --id EVENT_ID -y	Pro
Morning brief	python scripts/gcal_core.py brief	Pro

Setup

First-time setup required:

User must create Google Cloud project and OAuth credentials

Save client_secret.json to ~/.config/gcal-pro/

Run authentication:

python scripts/gcal_auth.py auth

Browser opens → user grants calendar access → done

Check auth status:

python scripts/gcal_auth.py status

Tiers

Free Tier

• View events (today, tomorrow, week, month)
• Search events
• List calendars
• Find free time slots

Pro Tier ($12 one-time)

• Everything in Free, plus:
• Create events
• Quick add (natural language)
• Update/reschedule events
• Delete events
• Morning brief via cron

Usage Patterns

Viewing Schedule

When user asks "What's on my calendar?" or "What do I have today?":

cd /path/to/gcal-pro
python scripts/gcal_core.py today

For specific ranges:

• "tomorrow" → python scripts/gcal_core.py tomorrow


• "this week" → python scripts/gcal_core.py week


• "meetings with Alex" → python scripts/gcal_core.py search -q "Alex"

Creating Events (Pro)

When user says "Add X to my calendar" or "Schedule Y":

Option 1: Quick add (natural language)

python scripts/gcal_core.py quick -q "Lunch with Alex Friday at noon"

Option 2: Structured create (via Python)

from scripts.gcal_core import create_event, parse_datetime

create_event(
    summary="Lunch with Alex",
    start=parse_datetime("Friday noon"),
    location="Cafe Roma",
    confirmed=True  # Set False to show confirmation prompt
)

Modifying Events (Pro)

⚠️ CONFIRMATION REQUIRED for destructive actions!

Before deleting or significantly modifying an event, ALWAYS confirm with the user:

Show event details

Ask "Should I delete/reschedule this?"

Only proceed with confirmed=True or -y flag after user confirms

Delete:

# First, find the event
python scripts/gcal_core.py search -q "dentist"
# Shows event ID

# Then delete (with user confirmation)
python scripts/gcal_core.py delete --id abc123xyz -y

Finding Free Time

When user asks "When am I free?" or "Find time for a 1-hour meeting":

python scripts/gcal_core.py free

Morning Brief (Pro + Cron)

Set up via Clawdbot cron to send daily agenda:

from scripts.gcal_core import generate_morning_brief
print(generate_morning_brief())

Cron setup example:

• Schedule: 8:00 AM daily


• Action: Run python scripts/gcal_core.py brief


• Delivery: Send output to user's messaging channel

Error Handling

Error

Cause

Solution

"client_secret.json not found"	Setup incomplete	Complete Google Cloud setup
"Token refresh failed"	Expired/revoked	Run python scripts/gcal_auth.py auth --force
"requires Pro tier"	Free user attempting write	Prompt upgrade or explain limitation
"Event not found"	Invalid event ID	Search for correct event first

Timezone Handling

• All times are interpreted in user's local timezone (default: America/New_York)
• When user specifies timezone (e.g., "2 PM EST"), honor it
• Display times in user's local timezone
• Store in ISO 8601 format with timezone

Response Formatting

For event lists, use this format:

📅 **Monday, January 27**
  • 9:00 AM — Team standup
  • 12:00 PM — Lunch with Alex 📍 Cafe Roma
  • 3:00 PM — Client call

📅 **Tuesday, January 28**
  • 10:00 AM — Dentist appointment 📍 123 Main St

For confirmations:

✓ Event created: "Lunch with Alex"
  📅 Friday, Jan 31 at 12:00 PM
  📍 Cafe Roma

For morning brief:

☀️ Good morning! Here's your day:
📆 Monday, January 27, 2026

You have 3 events today:
  • 9:00 AM — Team standup
  • 12:00 PM — Lunch with Alex
  • 3:00 PM — Client call

👀 Tomorrow: 2 events

File Locations

~/.config/gcal-pro/
├── client_secret.json   # OAuth app credentials (user provides)
├── token.json           # User's access token (auto-generated)

Integration with Clawdbot

This skill works with:

• Cron: Schedule morning briefs


• Memory: Store calendar preferences


• Messaging: Deliver briefs via Telegram/WhatsApp/etc.

Upgrade Prompt

When a Free user attempts a Pro action, respond:

⚠️ Creating events requires gcal-pro Pro ($12 one-time).

Pro includes: Create, edit, delete events + morning briefs.

👉 Upgrade: [gumroad-link]

For now, I can show you your schedule (free) — want to see today's events?