calendar 📅

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

Install

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

calendar auth --token ya29.a0AXooCgv...

Option 2: Create Your Own OAuth App

1. Go to Google Cloud Console
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

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

Calendars

calendar calendars                 # List your calendars
calendar calendars --json          # JSON output

Events

# 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 "[email protected]"

Event Details

calendar event <event-id>          # Show event details
calendar event abc123 --json       # JSON output

Create Event

# 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 "[email protected],[email protected]" \\
  --meet

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

Delete Event

calendar delete <event-id>

Check Availability

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:

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

# Get today's schedule
calendar events --today
calendar busy --date today

Schedule Meeting with Meet Link

# Create meeting with Google Meet
cal create \\
  --title "Sprint Planning" \\
  --start "tomorrow 10am" \\
  --duration 120 \\
  --meet \\
  --attendees "[email protected],[email protected],[email protected]"

Check Before Scheduling

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

Export Events

# 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.