Add a calendar plugin to find free overlapping times to meet with one or more people

.claude-plugin/marketplace.json

@@ -78,6 +78,11 @@
       "name": "hcp",
       "source": "./plugins/hcp",
       "description": "Generate HyperShift cluster creation commands via hcp CLI from natural language descriptions"
+    },
+    {
+      "name": "calendar",
+      "source": "./plugins/calendar",
+      "description": "A plugin to help find time and schedule meetings on your Google Calendar"
     }
   ]
-}
+}

PLUGINS.md

@@ -3,6 +3,7 @@
 This document lists all available Claude Code plugins and their commands in the ai-helpers repository.
 
 - [Agendas](#agendas-plugin)
+- [Calendar](#calendar-plugin)
 - [Ci](#ci-plugin)
 - [Component Health](#component-health-plugin)
 - [Doc](#doc-plugin)
@@ -27,6 +28,16 @@ A plugin to create various meeting agendas
 
 See [plugins/agendas/README.md](plugins/agendas/README.md) for detailed documentation.
 
+### Calendar Plugin
+
+find overlapping free time to meet with people
+
+**Commands:**
+- **`/calendar:create-event` `<natural_language_prompt_for_the_event>`** - Create a new event on Google Calendar.
+- **`/calendar:find-time` `<email_addresses> [duration_in_minutes] [days_ahead]`** - Find overlapping free time to meet with one or more people.
+
+See [plugins/calendar/README.md](plugins/calendar/README.md) for detailed documentation.
+
 ### Ci Plugin
 
 Miscellaenous tools for working with OpenShift CI

docs/data.json

@@ -550,6 +550,27 @@
         }
       ],
       "has_readme": true
+    },
+    {
+      "name": "calendar",
+      "description": "A plugin to help find time and schedule meetings on your Google Calendar",
+      "version": "0.0.1",
+      "commands": [
+        {
+          "name": "create-event",
+          "description": "Create a new event on Google Calendar.",
+          "synopsis": "/calendar:create-event <natural_language_prompt_for_the_event>",
+          "argument_hint": "<natural_language_prompt_for_the_event>"
+        },
+        {
+          "name": "find-time",
+          "description": "Find overlapping free time to meet with one or more people.",
+          "synopsis": "/calendar:find-time <email_addresses> [duration_in_minutes] [days_ahead]",
+          "argument_hint": "<email_addresses> [duration_in_minutes] [days_ahead]"
+        }
+      ],
+      "skills": [],
+      "has_readme": true
     }
   ]
 }

plugins/calendar/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "calendar",
+  "description": "find overlapping free time to meet with people",
+  "version": "0.0.1",
+  "author": {
+    "name": "github.com/openshift-eng"
+  }
+}

plugins/calendar/README.md

@@ -0,0 +1,196 @@
+# Calendar Plugin
+
+Google Calendar integration for Claude Code, providing AI-powered tools to find meeting times and schedule events seamlessly.
+
+## Features
+
+- 🔍 **Smart Time Finding** - Find overlapping free time across multiple participants' calendars
+- 📅 **Natural Language Event Creation** - Create calendar events using intuitive natural language descriptions
+- 🌐 **Timezone Handling** - Automatic timezone detection and conversion for global teams
+- 🤖 **Google Meet Integration** - Automatically adds Google Meet links to virtual meetings
+- ⚡ **Intelligent Parsing** - Understands relative dates, time expressions, and participant lists
+- 🎯 **Business Hours Optimization** - Prioritizes business hours and excludes weekends by default
+
+## Prerequisites
+
+- Claude Code installed
+- Google Calendar API access configured
+- Google Calendar MCP server running locally
+
+## Setup
+
+### 1. Google Cloud Setup
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com)
+2. Create a new project or select an existing one
+3. Enable the [Google Calendar API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com) for your project. Ensure that the right project is selected from the top bar before enabling the API
+4. Create OAuth 2.0 credentials:
+   - Go to **Credentials**
+   - Click **"Create Credentials"** > **"OAuth client ID"**
+   - Choose **"User data"** for the type of data that the app will be accessing
+   - Add your app name and contact information
+   - Add the following scopes:
+     - `https://www.googleapis.com/auth/calendar.events`
+     - `https://www.googleapis.com/auth/calendar`
+   - Select **"Desktop app"** as the application type (Important!)
+   - Download the auth key
+
+### 2. MCP Server Setup
+
+After completing the previous step, you need to set up the google-calendar MCP server locally.
+
+1. **Install the google-calendar MCP server** (if not already installed):
+   ```bash
+   npm install -g @cocal/google-calendar-mcp
+   ```
+
+2. **Set environment variable** for credentials:
+   ```bash
+   export GOOGLE_OAUTH_CREDENTIALS=~/.config/client_secret_xxxxxxxxx.json
+   ```
+
+3. **Add the MCP server to Claude Code** with the MCP server running:
+   ```bash
+   claude mcp add --transport stdio google-calendar -- npx @cocal/google-calendar-mcp
+   ```
+
+## Installation
+
+```bash
+# Add the marketplace (one-time setup)
+/plugin marketplace add openshift-eng/ai-helpers
+
+# Install the plugin
+/plugin install calendar@ai-helpers
+```
+
+## Available Commands
+
+### `/calendar:find-time` - Find Overlapping Free Time
+
+Find overlapping available time with multiple participants by analyzing calendar availability and suggesting optimal meeting times.
+
+**Usage:**
+```bash
+# Basic usage with two people
+/calendar:find-time [email protected],[email protected] 60
+
+# Including custom date range
+/calendar:find-time [email protected],[email protected] 30 7
+
+# Multiple participants with longer timeline
+/calendar:find-time [email protected],[email protected],[email protected] 45 15
+```
+
+**Features:**
+- Analyzes free/busy information across all participants
+- Filters out blocks shorter than requested duration
+- Excludes weekends unless specifically requested
+- Prioritizes business hours
+- Provides alternative suggestions if no perfect matches found
+- Displays times in user's primary calendar timezone
+
+See [commands/find-time.md](commands/find-time.md) for full documentation.
+
+---
+
+### `/calendar:create-event` - Create Calendar Events
+
+Create new calendar events using natural language descriptions with automatic Google Meet integration and intelligent parsing.
+
+**Usage:**
+```bash
+# Simple meeting
+/calendar:create-event Team standup tomorrow at 9am for 30 minutes
+
+# Meeting with specific attendees
+/calendar:create-event Project review Friday 2pm with [email protected] and [email protected]
+
+# Detailed planning session
+/calendar:create-event Quarterly planning session next Monday 10am-12pm with the whole engineering team
+
+# Quick 1:1 meeting
+/calendar:create-event Coffee chat with Sarah tomorrow 3pm for 45 minutes
+
+# All-hands meeting
+/calendar:create-event Monthly all-hands meeting first Friday of next month 2-3pm with leadership team
+```
+
+**Features:**
+- Natural language parsing for dates, times, and attendees
+- Automatic Google Meet link generation
+- Intelligent defaults (1-hour duration, virtual location)
+- Handles relative dates ("tomorrow", "next Friday", "in 2 hours")
+- Timezone conversion and validation
+- Email validation for attendees
+- Graceful error handling with helpful suggestions
+
+See [commands/create-event.md](commands/create-event.md) for full documentation.
+
+---
+
+## Workflow Examples
+
+### Planning a Team Meeting
+
+1. **Find available time:**
+   ```bash
+   /calendar:find-time [email protected],[email protected],[email protected],[email protected] 60 5
+   ```
+
+2. **Create the meeting:**
+   ```bash
+   /calendar:create-event Sprint planning session Thursday 2pm with [email protected],[email protected],[email protected],[email protected]
+   ```
+
+### Scheduling a Quick Sync
+
+```bash
+# One command to create immediate meeting
+/calendar:create-event Quick sync with John tomorrow 11am for 15 minutes
+```
+
+### Cross-timezone Meeting
+
+```bash
+# Find time considering global participants
+/calendar:find-time [email protected],[email protected],[email protected] 30 10
+
+# Create with specific timezone considerations
+/calendar:create-event Global standup next Monday 8am PST with [email protected],[email protected],[email protected]
+```
+
+## Troubleshooting
+
+### "Could not access calendar for {email}"
+- Verify the email address is correct
+- Ensure the user has shared their calendar or given appropriate permissions
+- Check that your Google Calendar API credentials have the necessary scopes
+
+### "No overlapping free time found"
+- Try a shorter meeting duration
+- Expand the date range (more days ahead)
+- Consider including weekend options
+- Check if participants have conflicting recurring meetings
+
+### OAuth/Authentication Issues
+- Verify `GOOGLE_OAUTH_CREDENTIALS` environment variable is set correctly
+- Ensure the credentials file exists and is readable
+- Check that the Google Calendar API is enabled in your Google Cloud project
+- Verify OAuth scopes include calendar access
+
+### MCP Server Issues
+- Ensure `@cocal/google-calendar-mcp` is installed and available
+- Check that the MCP server is properly configured in your Claude Code settings
+- Verify the MCP server is running and accessible
+- Check that the google-calendar MCP functions are available (e.g., `mcp__google-calendar__*`)
+- Verify network connectivity for API calls
+
+For command-specific troubleshooting, see the individual command documentation.
+
+## Security and Privacy
+
+- **Credentials**: OAuth credentials are stored locally and never transmitted to AI Helpers
+- **Calendar Data**: Free/busy information is queried in real-time and not stored
+- **Privacy**: Only calendar availability is accessed, not detailed event content
+- **Scope**: The plugin only requests minimal necessary Calendar API permissions

plugins/calendar/commands/create-event.md

@@ -0,0 +1,107 @@
+---
+description: Create a new event on Google Calendar.
+argument-hint: <natural_language_prompt_for_the_event>
+---
+
+## Name
+calendar:create-event
+
+## Synopsis
+```
+/calendar:create-event <natural_language_prompt_for_the_event>
+```
+
+## Description
+The `calendar:create-event` command creates a new calendar event on Google Calendar based on natural language input. It intelligently parses event details from user descriptions, automatically adds Google Meet links for virtual participation, and handles timezone conversions and date parsing.
+
+## Implementation
+
+### Phase 1: Parse Natural Language Input
+- Parse `$ARGUMENTS` to extract key event details:
+  - `summary` (event title/subject)
+  - `start` (start date and time)
+  - `end` (end date and time)
+  - `attendees` (list of email addresses)
+  - `description` (additional details, agenda, notes)
+- Handle relative date expressions ("tomorrow", "next Friday", "in 2 hours")
+- Parse time expressions ("9am", "2:30 PM", "noon")
+- Extract participant information from various formats
+
+### Phase 2: Validate and Clarify Missing Information
+- Check for essential information (event summary and start time)
+- If crucial details are missing, ask user for clarification with specific questions
+- Validate email addresses for attendees
+- Set reasonable defaults:
+  - Duration: 1 hour if end time not specified
+  - Location: Virtual (Google Meet) if not specified
+- Convert relative dates to absolute dates with proper timezone handling
+
+### Phase 3: Format Event Data
+- Convert all dates and times to ISO 8601 format
+- Use `mcp__google-calendar__get-current-time` function to determine user's timezone
+- Ensure start time is before end time
+- Format attendee list properly for calendar API
+- Prepare event description with any additional context
+
+### Phase 4: Ask For User Confirmation
+- Display the summary, meeting time, attendees, description 
+- Ask user to confirm
+- If user confirms, proceed to phase 5, otherwise, modify the summary, meeting time, attendees, description based on user's input until user confirms you correctly interpreted the intent.
+
+### Phase 5: Create Calendar Event
+- Use the `mcp__google-calendar__create-event` function from the google-calendar MCP server
+- Automatically attach Google Meet link for virtual participation using the `conferenceData` parameter
+- Create event on user's primary calendar (calendarId: 'primary')
+- Include all parsed attendees, description, and meeting details
+- Handle calendar API responses and potential conflicts
+
+### Phase 6: Confirmation and Error Handling
+- Confirm successful event creation with key details
+- Provide Google Meet link and calendar invitation status
+- Handle common errors gracefully:
+  - Calendar permission issues
+  - Invalid attendee emails
+  - Scheduling conflicts
+  - Timezone conversion errors
+- Suggest alternatives if event creation fails
+
+## Return Value
+- **Success Format**: Confirmation message with:
+  - Event title and time details
+  - List of invited attendees
+  - Google Meet link for virtual participation
+  - Calendar invitation status
+- **Error Format**: Clear error message with:
+  - Description of what went wrong
+  - Specific suggestions for resolution
+  - Alternative approaches if applicable
+
+## Examples
+
+1. **Simple meeting**:
+   ```
+   /calendar:create-event Team standup tomorrow at 9am for 30 minutes
+   ```
+
+2. **Meeting with specific attendees**:
+   ```
+   /calendar:create-event Project review Friday 2pm with [email protected] and [email protected]
+   ```
+
+3. **Detailed planning session**:
+   ```
+   /calendar:create-event Quarterly planning session next Monday 10am-12pm with the whole engineering team
+   ```
+
+4. **Quick 1:1 meeting**:
+   ```
+   /calendar:create-event Coffee chat with Sarah tomorrow 3pm for 45 minutes
+   ```
+
+5. **All-hands meeting**:
+   ```
+   /calendar:create-event Monthly all-hands meeting first Friday of next month 2-3pm with leadership team
+   ```
+
+## Arguments
+- `natural_language_prompt_for_the_event` ($1): Natural language description of the event to create, including title, time, attendees, and any other relevant details (required)