diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 323d0652..2329c650 100644 --- a/.claude-plugin/marketplace.json +++ b/.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" } ] -} \ No newline at end of file +} diff --git a/PLUGINS.md b/PLUGINS.md index df732e54..49f9f399 100644 --- a/PLUGINS.md +++ b/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` ``** - Create a new event on Google Calendar. +- **`/calendar:find-time` ` [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 diff --git a/docs/data.json b/docs/data.json index 13b37518..2e2fd02b 100644 --- a/docs/data.json +++ b/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 ", + "argument_hint": "" + }, + { + "name": "find-time", + "description": "Find overlapping free time to meet with one or more people.", + "synopsis": "/calendar:find-time [duration_in_minutes] [days_ahead]", + "argument_hint": " [duration_in_minutes] [days_ahead]" + } + ], + "skills": [], + "has_readme": true } ] } \ No newline at end of file diff --git a/plugins/calendar/.claude-plugin/plugin.json b/plugins/calendar/.claude-plugin/plugin.json new file mode 100644 index 00000000..78df8e3c --- /dev/null +++ b/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" + } +} diff --git a/plugins/calendar/README.md b/plugins/calendar/README.md new file mode 100644 index 00000000..191cd573 --- /dev/null +++ b/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 alice@company.com,bob@company.com 60 + +# Including custom date range +/calendar:find-time team@company.com,manager@company.com 30 7 + +# Multiple participants with longer timeline +/calendar:find-time alice@company.com,bob@company.com,carol@company.com 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 alice@company.com and bob@company.com + +# 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 team-lead@company.com,dev1@company.com,dev2@company.com,designer@company.com 60 5 + ``` + +2. **Create the meeting:** + ```bash + /calendar:create-event Sprint planning session Thursday 2pm with team-lead@company.com,dev1@company.com,dev2@company.com,designer@company.com + ``` + +### 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 alice@us.company.com,bob@uk.company.com,carol@asia.company.com 30 10 + +# Create with specific timezone considerations +/calendar:create-event Global standup next Monday 8am PST with alice@us.company.com,bob@uk.company.com,carol@asia.company.com +``` + +## 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 diff --git a/plugins/calendar/commands/create-event.md b/plugins/calendar/commands/create-event.md new file mode 100644 index 00000000..e2ee696c --- /dev/null +++ b/plugins/calendar/commands/create-event.md @@ -0,0 +1,107 @@ +--- +description: Create a new event on Google Calendar. +argument-hint: +--- + +## Name +calendar:create-event + +## Synopsis +``` +/calendar:create-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 alice@company.com and bob@company.com + ``` + +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) diff --git a/plugins/calendar/commands/find-time.md b/plugins/calendar/commands/find-time.md new file mode 100644 index 00000000..5b7c52f2 --- /dev/null +++ b/plugins/calendar/commands/find-time.md @@ -0,0 +1,80 @@ +--- +description: Find overlapping free time to meet with one or more people. +argument-hint: [duration_in_minutes] [days_ahead] +--- + +## Name +calendar:find-time + +## Synopsis +``` +/calendar:find-time [duration_in_minutes] [days_ahead] +``` + +## Description +The `calendar:find-time` command helps you find overlapping available time with people by analyzing calendar availability across multiple participants and suggesting optimal meeting times. + +## Implementation + +### Phase 1: Parse and Validate Arguments +- Parse `$ARGUMENTS` to extract email addresses, duration, and optional date range +- Validate email format for all participants +- Set default duration to be 30 minutes +- Set default date range if not provided (e.g., next 7 days) +- Convert duration to minutes if provided in other formats + +### Phase 2: Gather Free/Busy Information +- Use the `mcp__google-calendar__get-freebusy` function from the google-calendar MCP server to get busy times for all participants +- Query the specified days_ahead for each participant's calendar +- Get current time and primary calendar timezone using `mcp__google-calendar__get-current-time` + +### Phase 3: Analyze Available Time Slots +- Calculate free blocks by inverting busy periods for each participant +- Find overlapping free time across all participants +- Filter out blocks shorter than the requested duration +- Dismiss free blocks that are earlier than the current time +- Exclude weekends unless specifically requested +- Consider 9 AM - 6 PM as default preference + +### Phase 4: Generate Meeting Suggestions +- Sort potential meeting times by preference (earlier in week, business hours, etc.) +- Present top 3-5 options with clear time formatting +- Display times in the user's primary calendar timezone +- Include day of week and date for clarity +- Provide alternative suggestions if no perfect matches found + +### Phase 5: Error Handling +- Handle cases where no common free time exists +- Provide helpful suggestions (shorter duration, different date range) +- If you can't access a calendar, give up the operation gracefully. Then tell the user that the email address might be wrong +- Validate that all email addresses have accessible calendars + +## Return Value +- **Format**: Structured list of available meeting times +- **Content**: + - Meeting time options with date, time, and timezone + - Duration confirmation + - List of all participants + - Alternative suggestions if limited availability + +## Examples + +1. **Basic usage with two people**: + ``` + /calendar:find-time alice@company.com,bob@company.com 60 + ``` + +2. **Including date range**: + ``` + /calendar:find-time team@company.com,manager@company.com 30 7 + ``` + +3. **Multiple participants with specific date**: + ``` + /calendar:find-time alice@company.com,bob@company.com,carol@company.com 45 15 + ``` + +## Arguments +- `$1` (email_addresses): Comma-separated list of participant email addresses (required) +- `$2` (duration_in_minutes): Optional meeting duration in minutes +- `$3` (days_ahead): Optional number of days ahead to look up