# Gcal

> Google Calendar manager - create events, set reminders, list schedule via Google Calendar API. Use when the user says "add to calendar", "schedule", "reminder", "set reminder", "calendar event", "block time", "what's on my calendar", "today's schedule", "gcal", "create event", or wants to manage their Google Calendar.

- Skill: `theaayushstha1/gcal` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add theaayushstha1/gcal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theaayushstha1/gcal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: theaayushstha1 (https://skillmd.com/u/theaayushstha1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theaayushstha1/gcal

---


# Google Calendar Manager

Create events, set reminders, and view schedule via Google Calendar API.

## Prerequisites

1. Google OAuth must be set up: `python3 ~/.claude/skills/_google-auth/scripts/setup.py`
2. Google Calendar API enabled in Google Cloud project
3. Python packages: `google-auth-oauthlib`, `google-api-python-client`

## Command Routing

| User Says | Action |
|-----------|--------|
| "today's schedule", "what's on my calendar" | List today's events |
| "this week", "next 7 days" | List events for date range |
| "add event", "schedule meeting" | Create timed event |
| "reminder", "set reminder" | Create event with reminder notification |
| "block time for studying" | Create time block |

## Workflow: List Events

```bash
python3 ~/.claude/skills/gcal/scripts/list_events.py --date today
```

Options:
- `--date today` / `--date tomorrow` / `--date "2026-02-28"`
- `--days 7` (show next 7 days)
- `--max 20`

Present as a clean schedule:
```
## Today - Tuesday, Feb 25

| Time | Event | Location |
|------|-------|----------|
| 10:00 AM - 11:30 AM | CS 301 Lecture | Room 204 |
| 2:00 PM - 3:00 PM | GAUDON Client Call | Zoom |
| 7:00 PM - 9:00 PM | Study Group | Library |
```

## Workflow: Create Event

Parse natural language into event parameters, then run:

```bash
python3 ~/.claude/skills/gcal/scripts/create_event.py \
  --title "CS 301 Study Session" \
  --start "2026-02-26T15:00:00" \
  --end "2026-02-26T17:00:00"
```

Options:
- `--duration 120` (minutes, instead of --end)
- `--description "Review chapters 5-7"`
- `--location "Library Room 3"`
- `--reminder 60` (popup 60 min before; can repeat for multiple)
- `--date "2026-03-01"` (all-day event, instead of --start/--end)

## Workflow: Set Reminder

Reminders are events with notification overrides:

```bash
python3 ~/.claude/skills/gcal/scripts/create_event.py \
  --title "Submit Lab Report" \
  --start "2026-02-28T23:59:00" \
  --duration 15 \
  --reminder 60 --reminder 1440
```

This creates a 15-minute event with popups at 1 hour and 24 hours before.

## Natural Language Parsing

Convert user input to script arguments:

| User Says | Parsed |
|-----------|--------|
| "tomorrow 3pm-5pm" | `--start 2026-02-26T15:00:00 --end 2026-02-26T17:00:00` |
| "Friday at noon for 2 hours" | `--start 2026-02-28T12:00:00 --duration 120` |
| "next Monday" | `--date 2026-03-02` (all-day) |
| "remind me at 11:59pm" | `--start <date>T23:59:00 --duration 15 --reminder 30` |

Always use ISO 8601 format for dates/times. Use the current date context to resolve relative dates (today, tomorrow, next Monday, etc.).

## Error Handling

| Error | Solution |
|-------|----------|
| "OAuth credentials not found" | Run setup: `python3 ~/.claude/skills/_google-auth/scripts/setup.py` |
| "Token expired" | Script auto-refreshes; if fails, re-run setup |
| Event not appearing | Check timezone; script uses local timezone |
| Past date warning | Warn user if creating event in the past |

## Safety Rules

- Confirm event details before creating (show: title, time, reminders)
- Warn if event overlaps with existing events
- Never delete or modify existing events without explicit permission