calendar-window

name	calendar-window
description	Find available travel windows in your calendar by detecting hard constraints (meetings, exams, blocked dates) and identifying free blocks between commitments. Detects feasible date ranges that fit minimum trip duration, excludes blackout dates, and optimizes for consecutive days off. Use when checking schedule availability, finding gaps for trips, or identifying the best time to take PTO.

Calendar Window Finder

Find the gaps in your schedule — your next trip is hiding there.

Capabilities

• Constraint detection: Automatically identifies hard blocks (meetings, exams, events, busy status)
• Free block discovery: Finds consecutive days with no commitments
• Feasible range calculation: Only windows that fit your trip length
• Minimum duration filter: Skip gaps too short for your trip
• Weekend optimization: Prioritize Friday-Sunday departures
• Blackout exclusion: Skip holidays, busy periods, blocked dates
• PTO suggestions: Recommend which days to take off
• Multi-calendar: Check work + personal calendars together

How It Works

1. READ all calendars (work, personal, school...)
2. DETECT busy events → meetings, exams, all-day blocks
3. ADD blackout dates → holidays, known conflicts
4. SCAN for gaps → consecutive free days
5. FILTER by duration → min/max nights requirement
6. SCORE windows → weekend alignment, PTO efficiency
7. RANK → Present best options

Quick Usage

python3 scripts/find_windows.py \
  --min-nights 4 \
  --max-nights 7 \
  --search-days 90 \
  --weekends-priority

Parameters

Flag	Description	Example
--min-nights	Minimum trip length	3, 5, 7
--max-nights	Maximum trip length	7, 10, 14
--search-days	How far ahead to look	30, 90, 180
--weekends-priority	Prefer Fri-Sun departures	(flag)
--blackout-dates	Dates to exclude	2025-05-01:2025-05-05
--calendar-sources	Which calendars	work,personal
--pto-budget	Max days off to use	5, 10
--min-score	Minimum window quality	70

Output: Travel Windows

Detected Constraints

• Total blocked dates: Count of days with conflicts
• Constraint types: Meetings, exams, all-day events, OOO blocks

Travel Windows

Each window includes:

• 📅 Start — First day available
• 📅 End — Last day available (consecutive)
• 🌙 Nights — Total nights possible
• 📊 Score — Quality rating (weekend alignment, length)
• 💡 Suggestion — "Take Friday off for 4-day weekend"

Window Scoring

Factor	Weight	Description
Length	30%	Closer to max nights
Weekend	25%	Includes Sat-Sun
Friday	20%	Can extend with 1 PTO day
PTO efficiency	15%	Days off vs trip days ratio
Advance notice	10%	More time to plan = better

Integration with Other Agents

# SmartTripClaw uses this agent
windows = run_agent("calendar-window", {
    "min_nights": 4,
    "max_nights": 7
})

# For each window, check prices + weather
for window in windows:
    prices = run_agent("flight-search", window)
    weather = run_agent("weather", window)

Calendar Sources

Google Calendar

• OAuth setup required (one-time)
• Multiple calendars supported
• Reads busy/free status

Outlook/Office 365

• Microsoft Graph API
• Work calendar integration

Apple Calendar

• iCloud API (limited)
• Manual export option

Manual

• Paste your availability
• Override auto-detection

Advanced Features

PTO Optimization

--pto-budget 5  # You have 5 days off to use

Suggests which days maximize trip length.

Event Buffer

--buffer-days 1  # Needs 1 day recovery after trip

Ensures no events day after return.

Meeting Density Check

Skips weeks with heavy meeting load even if technically free.

See Also

• references/calendar_setup.md — OAuth configuration
• references/pto_strategies.md — Maximizing time off