# calendar 📅

Manage Google Calendar events, check availability, and schedule meetings from OpenClaw/Clawd.

## Install

```bash
# From this directory
npm link

# Or use directly
node /path/to/calendar-skill/calendar.js <command>
```

## Setup

Google Calendar uses OAuth 2.0 authentication. The easiest way to get a token:

### Option 1: OAuth Playground (Recommended for personal use)

1. Go to [Google OAuth Playground](https://developers.google.com/oauthplayground)
2. Click the settings gear (⚙️) and check "Use your own OAuth credentials"
3. Or just use the default Google credentials
4. Select scope: `https://www.googleapis.com/auth/calendar`
5. Click "Authorize APIs" and sign in
6. Click "Exchange authorization code for tokens"
7. Copy the "Access token"
8. Authenticate:

```bash
calendar auth --token ya29.a0AXooCgv...
```

### Option 2: Create Your Own OAuth App

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project or select existing
3. Enable the Google Calendar API
4. Go to Credentials → Create OAuth client ID → Desktop app
5. Download the client credentials
6. Use OAuth Playground or implement OAuth flow

Credentials are stored in `~/.config/calendar/credentials.json`.

## Commands

### Authentication
```bash
calendar auth --token <token>      # Save OAuth token
cal auth --token <token>           # Short alias
```

### Calendars
```bash
calendar calendars                 # List your calendars
calendar calendars --json          # JSON output
```

### Events
```bash
# List upcoming events
calendar events
calendar events --limit 20
calendar events --json

# Today's events
calendar events --today

# Tomorrow's events
calendar events --tomorrow

# This week's events
calendar events --this-week

# Date range
calendar events --from "2026-02-01" --to "2026-02-07"

# Specific calendar
calendar events --calendar "work@company.com"
```

### Event Details
```bash
calendar event <event-id>          # Show event details
calendar event abc123 --json       # JSON output
```

### Create Event
```bash
# Basic event
calendar create --title "Team Meeting" --start "2026-02-01T14:00:00"

# With duration (minutes)
calendar create --title "Lunch" --start "today 12pm" --duration 60

# With all options
calendar create \\
  --title "Project Review" \\
  --start "2026-02-01T15:00:00" \\
  --duration 90 \\
  --location "Conference Room A" \\
  --description "Q1 review meeting" \\
  --attendees "colleague@company.com,boss@company.com" \\
  --meet

# Quick syntax
cal create --title "Standup" --start "tomorrow 9am" --duration 30 --meet
```

### Delete Event
```bash
calendar delete <event-id>
```

### Check Availability
```bash
calendar busy                      # Today's schedule
calendar busy --date tomorrow      # Tomorrow's schedule
calendar busy --date "2026-02-15"  # Specific date
```

## Natural Language Dates

The skill supports natural language for dates:

- `today` - Current day
- `tomorrow` - Next day
- `today 2pm` - Today at 2 PM
- `tomorrow 9am` - Tomorrow at 9 AM
- `in 3 days` - 3 days from now
- ISO format: `2026-02-01T14:00:00`

## JSON Output

All commands support `--json` for structured output:

```bash
calendar events --today --json | jq '.[] | select(.location)'
calendar busy --json | jq '.eventCount'
```

## Security

- Credentials stored with 600 permissions (user-only)
- OAuth tokens expire after 1 hour (refresh tokens available for apps)
- No credentials logged or exposed
- Uses HTTPS for all API calls

## Examples

### Daily Briefing
```bash
# Get today's schedule
calendar events --today
calendar busy --date today
```

### Schedule Meeting with Meet Link
```bash
# Create meeting with Google Meet
cal create \\
  --title "Sprint Planning" \\
  --start "tomorrow 10am" \\
  --duration 120 \\
  --meet \\
  --attendees "dev1@company.com,dev2@company.com,pm@company.com"
```

### Check Before Scheduling
```bash
# Check if time slot is free
calendar busy --date "2026-02-15" --json | jq '.events | map(select(.start | contains("14:00"))) | length'
```

### Export Events
```bash
# Export this week's events to JSON
calendar events --this-week --json > this_week_events.json
```

## API Reference

This skill uses the Google Calendar API v3:
https://developers.google.com/calendar/api/v3/reference

Rate limits: 1,000,000 queries per day (generous)

## Troubleshooting

**"Authentication required" error**
- Run `calendar auth --token <token>`
- Token may have expired - get a new one from OAuth Playground

**"Invalid credentials" error**
- Token has expired (valid for 1 hour)
- Get a new access token

**"Calendar not found" error**
- Check calendar ID with `calendar calendars`
- Use full email for shared calendars

**Time zone issues**
- Events are created in your local timezone
- Google Calendar handles conversion for attendees

**Rate limiting**
- Unlikely to hit limits with personal use
- 1,000,000 queries/day quota

## Privacy Note

This skill accesses your Google Calendar data through the official API. Data is not stored locally except for the OAuth token. All API calls are made directly from your machine to Google's servers.