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)
└── license.json         # Pro license (if purchased)

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?