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"
``...

# gcal-pro

> Google Calendar skill for Clawdbot — manage your calendar through natural conversation.

**Pricing:** Free tier (read-only) | Pro $12 one-time (full access)

## Features

### Free Tier
- ✅ View today's events
- ✅ View tomorrow / this week
- ✅ Search events
- ✅ List calendars
- ✅ Find free time slots

### Pro Tier ($12)
- ✅ Everything in Free
- ✅ Create events
- ✅ Quick add (natural language)
- ✅ Update/reschedule events
- ✅ Delete events
- ✅ Morning brief (via Clawdbot cron)

## Installation

### Prerequisites
- Python 3.11+
- Google account
- Clawdbot installed

### Quick Start

1. **Install Python dependencies:**
   ```powershell
   pip install -r requirements.txt
   ```

2. **Set up Google Cloud:**
   - Follow [docs/GOOGLE_CLOUD_SETUP.md](docs/GOOGLE_CLOUD_SETUP.md)
   - Save `client_secret.json` to `~/.config/gcal-pro/`

3. **Authenticate:**
   ```powershell
   python scripts/gcal_auth.py auth
   ```

4. **Test:**
   ```powershell
   python scripts/gcal_core.py today
   ```

### One-Line Setup (after Google Cloud setup)
```powershell
.\scripts\setup.ps1
```

## Usage

### View Schedule
```bash
# Today's events
python scripts/gcal_core.py today

# Tomorrow
python scripts/gcal_core.py tomorrow

# This week
python scripts/gcal_core.py week

# Search
python scripts/gcal_core.py search -q "meeting"
```

### Create Events (Pro)
```bash
# Natural language
python scripts/gcal_core.py quick -q "Lunch with Alex Friday noon at Cafe Roma"
```

### Find Free Time
```bash
python scripts/gcal_core.py free
```

### Morning Brief
```bash
python scripts/gcal_core.py brief
```

## File Structure
```
gcal-pro/
├── SKILL.md              # Clawdbot skill definition
├── README.md             # This file
├── requirements.txt      # Python dependencies
├── PLAN.md               # Product plan & roadmap
├── scripts/
│   ├── gcal_auth.py      # OAuth authentication
│   ├── gcal_core.py      # Calendar operations
│   └── setup.ps1         # Windows setup script
├──...