apple calendar jxa

Managing a macOS calendar via an agent often fails due to slow AppleScript execution, permission hurdles, or imprecise searches. This skill provides a high-performance bridge to Apple Calendar using a hybrid backend strategy that combines EventKit JXA, Calendar.app scripting, and direct SQLite metadata lookups.

What it does

• High-speed agendas uses native EventKit to fetch date-range event lists without sequential scanning.
• SQLite keyword search performs instant read-only metadata lookups across all calendars for specific events.
• Event management handles creation, updates, and deletion of non-recurring events with verification steps.
• Cross-timezone travel creates complex flight events with separate departure and arrival time zones using private selectors.
• MapKit integration resolves airport locations to structured data for rich calendar location cards.
• Permission handling detects and explains macOS Automation, Full Disk Access, and EventKit authorization requirements.

How it works

1. The agent discovers available calendars using a lightweight JXA discovery script.
2. For broad date ranges, it executes an EventKit template to retrieve up to 1000 events in a 20-second window.
3. For specific searches, it queries Calendar.sqlitedb to find candidate IDs before resolving them via Calendar.app.
4. For updates, it assigns UTC ISO 8601 timestamps and verifies the modification by re-reading the event ID.

Frameworks & tools

This skill uses /usr/bin/osascript with the JavaScript (JXA) language flag. It interacts with the Foundation, EventKit, and MapKit Apple frameworks. It requires access to the host SQLite database at ~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb.

Why this beats prompting it yourself

Writing raw JXA often leads to timeout errors or silent failures when dealing with large calendars. This skill implements a sophisticated hybrid architecture that bypasses the slowness of cal.events().filter() by using faster lower-level APIs while maintaining the safety of the official application layer for writes.

Use cases

• Generate a summary of all meetings scheduled for the upcoming month across multiple calendars.
• Find an old appointment by searching for a specific keyword in the event notes or location.
• Batch create travel itineraries with precise local times and structured airport locations.
• Safely clean up duplicate events by resolving unique SQLite identifiers to JXA objects.

Known limitations

Full Disk Access is required for SQLite searches. EventKit requires specific macOS calendar permissions. Recurring event exceptions and complex recurrence rules are not supported for mutation.