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?