apple-calendar-jxa

Automate macOS Calendar.app through inline JXA with EventKit agendas and SQLite metadata search.

Updated Jul 20, 2026
One-click install
npx skills add https://github.com/roman-pinchuk/agent-skills --skill apple-calendar-jxa-roman-pinchuk
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: apple-calendar-jxa
Source: https://github.com/roman-pinchuk/agent-skills/tree/main/skills/apple-calendar-jxa
Command: npx skills add https://github.com/roman-pinchuk/agent-skills --skill apple-calendar-jxa-roman-pinchuk

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Reading and managing macOS Calendar events from an AI agent is slow and error-prone when done through naive JXA enumeration, and naive approaches break on recurring events, timezones, and permission boundaries. This Skill provides tested inline JXA templates that read agendas fast, search metadata safely, and perform verified writes without external wrapper scripts. ## Core Features & Use Cases - Fast EventKit Agendas: Fetch day, week, or month agendas across selected calendars in one bounded EventKit query with explicit IANA timezone handling and result limits. - SQLite Metadata Search: Run bounded, read-only keyword searches across event titles, descriptions, and locations, then resolve each candidate through Calendar.app before reading or mutating. - Verified Event Writes: Create, update, and delete non-recurring events by exact calendar name and event ID, with UTC ISO 8601 validation and post-write verification. - Use Case: Ask your agent to list all events in September 2026 in the Asia/Jerusalem timezone, find every event mentioning "dentist" across calendars, or create a cross-timezone flight event with departure and arrival zones. ## Quick Start Ask the agent to list all my calendar events for next week using the apple-calendar-jxa skill.

Frequently Asked Questions about apple-calendar-jxa

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I read macOS Calendar events from a script?

Use inline JXA with osascript -l JavaScript to query EventKit's predicateForEventsWithStartDateEndDateCalendars for a bounded date range. This returns all matching events across selected calendars in one fetch, far faster than enumerating calendars through Calendar.app.

How to search Apple Calendar events by keyword?

Run a bounded read-only SQLite query against the Calendar database matching the term in event title, description, and location with LIKE escaping. Treat each row as a candidate and resolve it through Calendar.app JXA by ID before reading details or mutating.

Does JXA Calendar automation require special macOS permissions?

Yes, three separate permissions apply: Automation consent to control Calendar.app, EventKit full calendar access for agenda reads, and Full Disk Access for SQLite metadata search. Each is checked explicitly and the workflow stops with an explanation if access is missing.

Can I edit recurring Calendar events with JXA?

The generic JXA mutation snippets apply only to non-recurring events. When a resolved candidate has recurrence indicators, the workflow stops and asks whether you mean a single occurrence or the whole series, since occurrence-aware editing is not supported.

Why does Calendar.app JXA fail to list calendar IDs?

On some macOS versions, calling id() on calendars raises AppleEvent error -10000. The workaround is to list only names and writable status, then resolve operations by exact unique calendar name instead of ID.

What are the limitations of SQLite Calendar search?

SQLite search requires Full Disk Access, uses private schema that may change between macOS versions, and returns stored series candidates rather than expanded recurring occurrences. Rows can be stale after sync, so results must be resolved through Calendar.app before use.