✓ Verified 💻 Development ✓ Enhanced Data

Gcal Pro

Google Calendar integration for viewing, creating, and managing.

Rating: 4.1 (258 reviews)
Downloads: 3,708 downloads
Version: 1.0.0

Overview

Google Calendar integration for viewing, creating, and managing.

Complete Documentation

View Source →

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:

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

bash

python scripts/gcal_auth.py auth

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:

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

text

📅 **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:

text

✓ Event created: "Lunch with Alex"
  📅 Friday, Jan 31 at 12:00 PM
  📍 Cafe Roma

For morning brief:

text

☀️ 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

text

~/.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?

Installation

Terminal bash


openclaw install gcal-pro

Copied!

💻Code Examples

python scripts/gcal_core.py today

python-scriptsgcalcorepy-today.txt

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

)

.txt

### 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:**

python scripts/gcal_core.py delete --id abc123xyz -y

python-scriptsgcalcorepy-delete---id-abc123xyz--y.txt

### Finding Free Time

When user asks "When am I free?" or "Find time for a 1-hour meeting":

python scripts/gcal_core.py free

python-scriptsgcalcorepy-free.txt

### Morning Brief (Pro + Cron)

Set up via Clawdbot cron to send daily agenda:

print(generate_morning_brief())

printgeneratemorningbrief.txt

**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:**

example.py

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
)

example.sh

# 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

example.txt

📅 **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

example.txt

✓ Event created: "Lunch with Alex"
  📅 Friday, Jan 31 at 12:00 PM
  📍 Cafe Roma

example.txt

☀️ 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