Native macOS personal information management for calendars, reminders, contacts, and local Mail.app. Use when the user wants to schedule meetings, create events, check their calendar, create or complete reminders, look up contacts, find someone's phone number or email, manage tasks and to-do lists, triage local Mail.app messages, or troubleshoot EventKit, Contacts, or Mail.app permissions on macOS.
Manages macOS calendars, reminders, contacts, and local Mail.app for scheduling, tasks, and contact lookups.
npx claudepluginhub omarshahine/apple-pim-agent-pluginThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/contacts-api.mdreferences/eventkit-api.mdreferences/mail-jxa.mdApple provides frameworks and scripting interfaces for personal information management:
EventKit and Contacts require explicit user permission via privacy prompts. Mail.app requires Automation permission and must be running.
For detailed API property tables and code examples, see:
references/eventkit-api.md — EKEvent, EKReminder, EKCalendar, recurrence rules, alarmsreferences/contacts-api.md — CNContact, labeled values, groupsreferences/mail-jxa.md — JXA message properties, batch fetching, Mail.app vs Fastmail scopeEach PIM domain requires separate macOS authorization:
| Domain | Framework | Permission Section |
|---|---|---|
| Calendars | EventKit | Privacy & Security > Calendars |
| Reminders | EventKit | Privacy & Security > Reminders |
| Contacts | Contacts | Privacy & Security > Contacts |
| Automation (JXA) | Privacy & Security > Automation |
| State | Meaning | Action |
|---|---|---|
notDetermined | Never requested | Use apple-pim with action authorize to trigger prompt |
authorized | Full access granted | Ready to use |
denied | User refused access | Must enable in System Settings manually |
restricted | System policy (MDM, parental) | Cannot override |
writeOnly | Limited write access (macOS 17+) | Upgrade to Full Access in Settings |
Permissions must be granted on the Mac where the CLI runs. SSH does not inherit GUI-level permission dialogs. Grant permissions locally first.
The PIM CLIs share a configuration system for filtering calendars/reminder lists and setting defaults.
| Path | Purpose |
|---|---|
~/.config/apple-pim/config.json | Base configuration |
~/.config/apple-pim/profiles/{name}.json | Named profile overrides |
{
"calendars": {
"enabled": true,
"mode": "blocklist",
"items": ["US Holidays", "Birthdays"],
"default": "Personal"
},
"reminders": {
"enabled": true,
"mode": "allowlist",
"items": ["Tasks", "Shopping", "Work"],
"default": "Tasks"
},
"contacts": {
"enabled": true
},
"mail": {
"enabled": true
}
}
| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether the domain is active (default: true) |
mode | string | Filter mode: all, allowlist, or blocklist (default: all) |
items | string[] | Calendar/list names for allowlist or blocklist |
default | string | Default calendar or list for creating new items |
| Mode | Behavior |
|---|---|
all | No filtering — all calendars/lists are visible (default) |
allowlist | Only calendars/lists named in items are visible |
blocklist | All calendars/lists are visible EXCEPT those named in items |
Profiles allow different configurations for different contexts (e.g., work vs personal).
Selection priority: --profile CLI flag > APPLE_PIM_PROFILE env var > base config only.
Merge semantics: A profile replaces entire domain sections. If a profile defines calendars, it completely replaces the base calendars config (not a field-by-field merge).
apple-pim with action config_show: Returns the current resolved config after profile merging. Shows domains, filters, defaults, and paths.apple-pim with action config_init: Lists all available calendars and reminder lists from macOS with their sources and system defaults. Does NOT write any files.Both accept an optional profile parameter.
When creating events or reminders, the default calendar/list is resolved in this order:
--calendar or --list parameterdefault value for the domainThere is no MCP tool for writing config files. Users must manually create or edit ~/.config/apple-pim/config.json. Use apple-pim with action config_init to discover available calendars/lists, then guide the user on creating the config.
.thisEvent vs .futureEvents span for recurring event edits (see EKSpan below)allowsContentModifications before attempting writescalendar with action batch_create when creating multiple events for efficiencyEventKit uses EKSpan to control which occurrences are affected by save/delete operations:
| Span | Effect | When to Use |
|---|---|---|
.thisEvent | Affects only the single occurrence | Default for delete and update. Use when cancelling one meeting. |
.futureEvents | Affects this and all future occurrences | Use when ending a series or changing the pattern going forward. |
.thisEvent. Pass --future-events to use .futureEvents..thisEvent. Pass --future-events to apply changes to all future occurrences.recurrence: { frequency: "none" } with --future-events to convert a recurring event into a single event.When reading events/reminders, the recurrence array includes:
frequency: daily, weekly, monthly, yearlyinterval: repeat every N periodsdaysOfTheWeek: which days (e.g., ["monday", "wednesday", "friday"])daysOfTheMonth: which days of month (e.g., [1, 15])endDate or occurrenceCount: when the series endsoverdue for urgent items, today for daily planning, week for weekly reviewreminder with action batch_complete, batch_delete) when acting on multiple itemsmail with action batch_update, batch_delete) for inbox triageapple-pim action status when encountering errorsapple-pim action authorize to request access for notDetermined domainsdenied domainsSupport flexible input:
2024-01-15T14:30:00CNContact.predicateForContacts(matchingName:)CNContact.predicateForContacts(withIdentifiers:)eventStore.predicateForEvents(withStart:end:calendars:)apple-pim with action status to check all domains at onceapple-pim with action authorize to trigger permission promptsapple-pim with action config_show to verify the active config. Check if an unexpected profile is being applied via APPLE_PIM_PROFILE env var.apple-pim with action config_init to see all available calendars/lists from macOS, then compare with action config_show to see what's being filtered.--profile flag > APPLE_PIM_PROFILE env var > base config. Profile files must be at ~/.config/apple-pim/profiles/{name}.json.config.json has invalid JSON, CLIs fall back to default behavior (all domains enabled, no filtering). Use apple-pim with action config_show to verify — it reports the config path and whether it was loaded successfully.Expert guidance for Next.js Cache Components and Partial Prerendering (PPR). **PROACTIVE ACTIVATION**: Use this skill automatically when working in Next.js projects that have `cacheComponents: true` in their next.config.ts/next.config.js. When this config is detected, proactively apply Cache Components patterns and best practices to all React Server Component implementations. **DETECTION**: At the start of a session in a Next.js project, check for `cacheComponents: true` in next.config. If enabled, this skill's patterns should guide all component authoring, data fetching, and caching decisions. **USE CASES**: Implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, debugging cache issues, and reviewing Cache Component implementations.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.