gcal-pro

# 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 ``` 4. 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?