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:

1. User must create Google Cloud project and OAuth credentials
2. Save client_secret.json to ~/.config/gcal-pro/
3. Run authentication:

bash python scripts/gcal_auth.py auth

1. Browser opens → user grants calendar access → done

Check auth status:

bash
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?":

bash
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)

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

Option 2: Structured create (via Python)

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:

1. Show event details
2. Ask "Should I delete/reschedule this?"
3. Only proceed with confirmed=True or -y flag after user confirms

Delete:

bash
# 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":

bash
python scripts/gcal_core.py free

Morning Brief (Pro + Cron)

Set up via Clawdbot cron to send daily agenda:

python
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?