Calendar Scheduling

Tools for calendar event management, conflict detection, and intelligent scheduling.

Quick Start

Format calendar event:

python scripts/format_event.py --title "Team Meeting" --start "2026-01-20 14:00" --duration "1h" --output event.json

Detect conflicts:

python scripts/detect_conflicts.py --events existing_events.json --new-event new_event.json

Find free time:

python scripts/find_free_time.py --calendars user1.json user2.json --duration "1h" --business-hours

Event Formatting

Standard Event Structure

Google Calendar format:

{
  "summary": "Team Meeting",
  "description": "Weekly team sync",
  "start": {
    "dateTime": "2026-01-20T14:00:00-08:00",
    "timeZone": "America/Los_Angeles"
  },
  "end": {
    "dateTime": "2026-01-20T15:00:00-08:00",
    "timeZone": "America/Los_Angeles"
  },
  "attendees": [
    {"email": "user1@example.com"},
    {"email": "user2@example.com"}
  ],
  "location": "Conference Room A",
  "reminders": {
    "useDefault": false,
    "overrides": [
      {"method": "popup", "minutes": 15}
    ]
  }
}

Event Types

1. Meeting

{
  "summary": "Product Review Meeting",
  "duration": "1h",
  "attendees": ["team@example.com"],
  "location": "Zoom",
  "reminders": [15]
}

2. All-Day Event

{
  "summary": "Company Holiday",
  "start": {"date": "2026-01-20"},
  "end": {"date": "2026-01-21"}
}

3. Recurring Event

{
  "summary": "Weekly Standup",
  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"],
  "start": "2026-01-20T09:00:00",
  "duration": "15m"
}

4. Focus Time

{
  "summary": "Focus: Deep Work",
  "transparency": "opaque",
  "visibility": "private",
  "duration": "2h"
}

Conflict Detection

Detection Algorithm

def detect_conflicts(existing_events: list, new_event: dict) -> list:
    """
    Detect scheduling conflicts.

    Returns list of conflicting events.
    """
    conflicts = []
    new_start = parse_datetime(new_event['start'])
    new_end = parse_datetime(new_event['end'])

    for event in existing_events:
        event_start = parse_datetime(event['start'])
        event_end = parse_datetime(event['end'])

        # Check for overlap
        if (new_start < event_end and new_end > event_start):
            conflicts.append(event)

    return conflicts

Conflict Types

Hard Conflicts:

• Overlapping meetings
• Double-booked time slots
• Events during blocked time

Soft Conflicts:

• Back-to-back meetings (no buffer)
• Meetings during preferred focus time
• Too many meetings in one day
• Meetings outside business hours

Buffer Time

Add buffer between meetings:

BUFFER_MINUTES = 15

def has_buffer(event1, event2, buffer_minutes=15):
    """Check if events have sufficient buffer."""
    gap = event2_start - event1_end
    return gap.total_seconds() >= (buffer_minutes * 60)

Smart Scheduling

Find Free Time

Algorithm to find available time slots:

def find_free_time(
    calendars: list,
    duration_minutes: int,
    start_date: datetime,
    end_date: datetime,
    business_hours_only: bool = True
) -> list:
    """
    Find available time slots across multiple calendars.

    Returns list of (start, end) tuples.
    """
    # 1. Collect all busy times
    busy_times = []
    for calendar in calendars:
        busy_times.extend(get_busy_times(calendar))

    # 2. Sort busy times
    busy_times.sort(key=lambda x: x[0])

    # 3. Find gaps
    free_slots = []
    current_time = start_date

    for busy_start, busy_end in busy_times:
        # Check gap before this busy time
        if (busy_start - current_time).total_seconds() >= duration_minutes * 60:
            # Filter by business hours
            if business_hours_only:
                slot = filter_business_hours(current_time, busy_start)
                if slot:
                    free_slots.append(slot)
            else:
                free_slots.append((current_time, busy_start))

        current_time = max(current_time, busy_end)

    return free_slots

Business Hours

Default business hours:

BUSINESS_HOURS = {
    'monday': {'start': '09:00', 'end': '17:00'},
    'tuesday': {'start': '09:00', 'end': '17:00'},
    'wednesday': {'start': '09:00', 'end': '17:00'},
    'thursday': {'start': '09:00', 'end': '17:00'},
    'friday': {'start': '09:00', 'end': '17:00'},
    'saturday': None,  # Not a business day
    'sunday': None     # Not a business day
}

Meeting Optimization

Optimal meeting times:

1. Mid-morning (10:00-11:30): Good for focused discussions
2. Early afternoon (13:00-14:30): Good for collaborative work
3. Avoid:
   • Early morning (before 9:00)
   • Lunch time (12:00-13:00)
   • Late afternoon (after 16:00)
   • End of week (Friday afternoon)

Meeting length guidelines:

• Quick sync: 15 minutes
• Standard meeting: 30 minutes
• Deep dive: 60 minutes
• Workshop: 90-120 minutes
• All-hands: 30-45 minutes

Reminder Scheduling

Reminder Types

Time-based:

• 15 minutes before (default)
• 1 hour before
• 1 day before
• 1 week before (for important events)

Context-based:

• When leaving for meeting (travel time)
• When prep needed (read docs)
• When action required (submit materials)

Smart Reminders

def calculate_reminder_time(event: dict) -> int:
    """
    Calculate optimal reminder time based on event type.

    Returns minutes before event.
    """
    event_type = event.get('type', 'meeting')
    duration = event.get('duration_minutes', 30)

    if event_type == 'interview':
        return 60  # 1 hour before
    elif event_type == 'presentation':
        return 120  # 2 hours before (prep time)
    elif event_type == 'external_meeting':
        return 30  # 30 minutes before
    elif duration >= 60:
        return 30  # Long meetings: 30 min before
    else:
        return 15  # Short meetings: 15 min before

Scripts

format_event.py

Format a calendar event.

Usage:

python scripts/format_event.py \
    --title "Team Meeting" \
    --start "2026-01-20 14:00" \
    --duration "1h" \
    --attendees "user1@example.com,user2@example.com" \
    --location "Conference Room A" \
    --reminder 15 \
    --output event.json

Arguments:

• --title

  : Event title (required)

• --start

  : Start date/time (YYYY-MM-DD HH:MM)

• --duration

  : Duration (e.g., "1h", "30m")

• --attendees

  : Comma-separated email addresses

• --location

  : Meeting location or video link

• --reminder

  : Reminder minutes before event

• --output

  : Output JSON file

detect_conflicts.py

Detect scheduling conflicts.

Usage:

python scripts/detect_conflicts.py \
    --events existing_events.json \
    --new-event new_event.json \
    --buffer 15

Arguments:

• --events

  : JSON file with existing events

• --new-event

  : JSON file with new event to check

• --buffer

  : Required buffer minutes between events

Output:

{
  "has_conflicts": true,
  "hard_conflicts": [
    {
      "event": "Existing Meeting",
      "start": "2026-01-20T14:00:00",
      "end": "2026-01-20T15:00:00",
      "reason": "Overlapping time slot"
    }
  ],
  "soft_conflicts": [
    {
      "event": "Previous Meeting",
      "reason": "No buffer time (back-to-back)"
    }
  ]
}

find_free_time.py

Find available time slots.

Usage:

python scripts/find_free_time.py \
    --calendars user1.json user2.json \
    --duration "1h" \
    --start "2026-01-20" \
    --end "2026-01-27" \
    --business-hours \
    --timezone "America/Los_Angeles"

Arguments:

• --calendars

  : JSON files with calendar events

• --duration

  : Required duration (e.g., "1h", "30m")

• --start

  : Start date to search from

• --end

  : End date to search until

• --business-hours

  : Only suggest business hours

• --timezone

  : Timezone for results

Output:

{
  "suggested_times": [
    {
      "start": "2026-01-20T10:00:00-08:00",
      "end": "2026-01-20T11:00:00-08:00",
      "score": 95,
      "reason": "Optimal time (mid-morning)"
    },
    {
      "start": "2026-01-20T14:00:00-08:00",
      "end": "2026-01-20T15:00:00-08:00",
      "score": 85,
      "reason": "Good time (early afternoon)"
    }
  ]
}

Scheduling Rules

See

rules/scheduling_rules.md

for detailed scheduling guidelines:

General Rules

1. Meeting Length

• Default to 25 or 50 minutes (not 30 or 60)
• Allows 5-10 minute buffer
• Prevents back-to-back fatigue

2. Meeting Frequency

• Max 4 hours of meetings per day
• Max 2 hours consecutive meetings
• One meeting-free day per week

3. Meeting Timing

• Schedule important meetings mid-morning
• Avoid Monday morning and Friday afternoon
• Respect timezones (for distributed teams)

4. Attendees

• Invite only necessary attendees
• Max 8 people for productive discussions
• Provide agenda in advance

Focus Time

Block focus time:

• Morning: 9:00-11:00 (deep work)
• Afternoon: 14:00-16:00 (focused tasks)

Protection:

• Mark as "busy" in calendar
• Decline meeting requests during focus time
• Schedule at least 2 hours per day

Time Zones

COMMON_TIMEZONES = {
    'PT': 'America/Los_Angeles',
    'ET': 'America/New_York',
    'UTC': 'UTC',
    'GMT': 'Europe/London',
    'CET': 'Europe/Paris',
    'IST': 'Asia/Kolkata',
    'JST': 'Asia/Tokyo'
}

def find_overlap_hours(timezone1, timezone2):
    """Find overlapping business hours between timezones."""

Integration with Agents

Scheduling Agent

from calendar_scheduling import find_free_time, format_event

# Find available time
free_slots = find_free_time(
    calendars=[user1_calendar, user2_calendar],
    duration_minutes=60,
    business_hours_only=True
)

# Format event
event = format_event(
    title="Team Sync",
    start=free_slots[0]['start'],
    duration="1h",
    attendees=['user1@example.com', 'user2@example.com']
)

# Create in Google Calendar
calendar_client.create_event(event)

Communication Agent

from calendar_scheduling import detect_conflicts

# Check for conflicts before accepting invite
conflicts = detect_conflicts(existing_events, new_invite)

if conflicts['has_conflicts']:
    # Send message suggesting alternative time
    message = f"I have a conflict at that time. Alternative times: {suggest_alternatives()}"
    slack_client.send_message(message)

Best Practices

Event Creation

• Clear, descriptive titles
• Include agenda in description
• Add video link for remote meetings
• Set appropriate reminders
• Invite only necessary attendees

Conflict Management

• Check for conflicts before accepting
• Suggest alternative times
• Respect focus time blocks
• Decline unnecessary meetings

Meeting Hygiene

• Start and end on time
• Provide agenda in advance
• Take and share notes
• Follow up with action items
• Cancel if unnecessary

Calendar Maintenance

• Block focus time weekly
• Review and optimize calendar monthly
• Clean up old/canceled events
• Keep time zones updated
• Maintain consistent meeting patterns

Examples

• examples/weekly_sync_event.json

  - Weekly team meeting

• examples/one_on_one_event.json

  - 1:1 meeting format

• examples/all_hands_event.json

  - Company all-hands