apple-reminders

name	apple-reminders
description	Use Apple Reminders from Codex through the local Apple Reminders MCP plugin. Trigger for reminder list/search/read/create/update/complete/delete/move workflows and relative-date requests like nearest reminder.

Apple Reminders

Use this skill when a task should access local Apple Reminders.

Fast routing

• First use, a new Mac, or permission failures: reminders_request_permissions.
• Reminder lookup, nearest reminder, or scheduled reminders: reminders_search, then reminders_read if body/details matter.
• Writes: call the mutating tool with dryRun: true for a preview, then repeat with confirm: true only after the user clearly confirms.

First-run setup behavior

• If the user asks to set up the plugin, mentions a fresh clone/new Mac, or hits an access error, call reminders_request_permissions before any reminders list/search/read/write tool.
• Treat permission output as an onboarding checklist: summarize the next step in plain language, ask the user to approve macOS prompts or System Settings toggles when needed, then retry only after they say it is done.
• Do not use real reminder notes to test permissions. The setup tool is the privacy-light probe.

Workflow

• Use reminders_list_lists when the user asks what lists are available or when a target list is ambiguous.
• Use reminders_search for reminder candidates and handles.
• For "nearest reminder", "next reminder", and other upcoming scheduled-reminder requests, use reminders_search with completed: "incomplete", scheduled: "scheduled", scheduledSince set to the current local ISO datetime, sort: "scheduled", and a small limit.
• Do not infer "no upcoming reminders" from a broad incomplete-only search. Scheduled/date-range searches scan the complete selected lists before applying limit, because EventKit fetch order is not chronological; maxScanPerList is only a relevance-scan performance cap and should not be used as a correctness boundary for nearest/upcoming lookups.
• For due-only or reminder-alarm-only questions, use dueSince/dueBefore or remindSince/remindBefore directly. Those date-range searches also scan complete selected lists before limiting.
• Use reminders_read only for selected reminders and keep body limits tight.
• Use reminders_create, reminders_update, reminders_complete, reminders_delete, and reminders_move only when the configured write guard allows it.
• Treat reminders_delete as real reminder deletion, not a move-to-trash workflow.
• Swift/EventKit-backed Reminders support includes title, notes/body, due date, reminder alarms, priority, URL, recurrence, completion state, and moving between lists. Do not promise tags, subtasks, or attachments.

For relative dates, compute the actual current local ISO datetime before calling tools. Reminders accepts ISO date or datetime strings.

Examples

Find the next scheduled incomplete reminder:

reminders_search({"completed":"incomplete","scheduled":"scheduled","scheduledSince":"2026-05-17T19:10:00+02:00","sort":"scheduled","limit":5})

Find overdue reminders by due date:

reminders_search({"completed":"incomplete","dueBefore":"2026-05-17T19:10:00+02:00","sort":"scheduled","limit":10})

Search reminder titles/notes/list names:

reminders_search({"query":"rent","completed":"all","limit":10})
reminders_read({"handles":["<handle-from-search>"],"maxBodyChars":1000})

Create a reminder with the write guard:

reminders_create({"name":"Pay rent","dueDate":"2026-05-26T23:00:00+02:00","remindMeDate":"2026-05-26T23:00:00+02:00","dryRun":true})
reminders_create({"name":"Pay rent","dueDate":"2026-05-26T23:00:00+02:00","remindMeDate":"2026-05-26T23:00:00+02:00","confirm":true})

Complete, move, or delete a selected reminder:

reminders_complete({"handles":["<handle>"],"dryRun":true})
reminders_complete({"handles":["<handle>"],"confirm":true})
reminders_move({"handles":["<handle>"],"list":"Tasks","dryRun":true})
reminders_move({"handles":["<handle>"],"list":"Tasks","confirm":true})
reminders_delete({"handles":["<handle>"],"dryRun":true})
reminders_delete({"handles":["<handle>"],"confirm":true})

Access mode

• APPLE_REMINDERS_WRITE_MODE=ask is the default. Mutating tools return a preview or target summary unless the call includes confirm: true.
• APPLE_REMINDERS_WRITE_MODE=direct means full local write access.

Privacy

Do not paste large reminder notes unless the user explicitly asks. Prefer concise summaries and cite handles, titles, lists, and dates.