← Back to Calendar & Scheduling
Calendar & Scheduling by @bilalmohamed187-cpu

gcal-pro

Google Calendar: view, create, manage events with natural language

Source Code

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:
    python scripts/gcal_auth.py auth
  4. 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:

  1. Show event details
  2. Ask "Should I delete/reschedule this?"
  3. 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?