Apple Reminders for Obsidian

Apple Reminders for Obsidian is a macOS desktop plugin for working with Apple Reminders directly inside your vault. It adds a dedicated Reminders view, lets you drag reminders into Markdown notes, creates linked reminder notes, and keeps completion state in sync between Obsidian and Apple Reminders.

Everything runs locally on your Mac. The plugin uses AppleScript out of the box and can optionally use a native Swift helper for faster Reminders access.

What This Plugin Does

Apple Reminders View

• Adds a dedicated Apple Reminders view to Obsidian.
• Opens from the ribbon icon or command palette.
• Can open in the right sidebar, a normal tab, or a popout window.
• Shows Reminders lists with names, colors, custom icons, and incomplete counts.
• Shows smart-list counts such as today, scheduled, all, flagged, and completed when available.
• Displays reminders with title, notes, due date, priority, completion state, and linked-note status.
• Supports manual refresh and full sync.
• Supports automatic refresh in balanced/live modes.
• Preserves a selected list between sessions.
• Can defer startup loading so Obsidian opens faster.

Reminder Completion

• Complete reminders from the Obsidian Reminders view.
• Update the visible row and list counts after completion.
• Complete linked Markdown checkboxes and push that state back to Apple Reminders.
• Complete rendered reminder cards and push that state back to Apple Reminders.
• Pull completion changes from Apple Reminders back into linked notes.
• Choose bidirectional sync or one-way sync in either direction.

Drag and Drop Into Notes

Drag reminders from the Reminders view into Markdown notes in source mode.

Supported insert formats:

• Inline checkbox: a Markdown task with a hidden reminder ID.
• Embedded card: an apple-reminder code block that renders as an interactive card.
• Plain text: the reminder title only.
• Always ask: choose the format at drop time.

Hold Option while dropping to force plain text insertion.

The plugin avoids inserting linked reminder content into unsafe locations such as fenced code blocks and Markdown tables.

Linked Reminder Checkboxes

Inline checkbox drops look like this:

- [ ] Renew passport *(due: July 12)* <!-- reminder-id: x-apple-reminder://... -->

The hidden reminder-id comment is what lets the plugin identify the Apple Reminders item later. When sync allows it, checking or unchecking the task in Obsidian updates the original reminder.

Embedded Reminder Cards

Embedded card drops use an apple-reminder code block:

```apple-reminder
id: x-apple-reminder://...
style: markdown
title: Renew passport
listName: Personal
dueDate: Monday, July 12, 2026 at 9:00:00 AM
priority: 5
notes: Bring photo and old passport.
```

Cards render inside reading mode with completion controls, reminder metadata, notes, refresh controls, and orphan warnings when the original reminder can no longer be found.

Card styles:

• Obsidian / Markdown: fits Obsidian's native note style.
• Apple: closer to the Apple Reminders visual style.

Linked Notes

Each reminder row can create or open a dedicated linked note.

Linked notes:

• Start with a reminder header block.
• Can render the header as a banner or card.
• Are tracked in link-registry.json.
• Open from the reminder row when already linked.
• Can be stored in a default folder.
• Can use per-list destination folders.
• Are protected against accidental duplicate reminder links when a note is copied.
• Stay linked after note renames.
• Clean up registry entries when notes are deleted.

Orphan Handling

If a linked reminder no longer exists in Apple Reminders, the plugin marks the linked note content as orphaned and can help clean it up.

Orphan handling works for:

• Linked checkbox lines.
• Embedded reminder cards.
• Linked note header blocks.

Native macOS Integration

The plugin has two backend paths:

• AppleScript: default, no extra install.
• Native Swift helper: optional EventKit helper for faster list and reminder reads.

Backend mode can be:

• Automatic: use the native helper when installed, otherwise AppleScript.
• Native helper: require the helper.
• AppleScript: force AppleScript.

The helper is optional. The plugin still works without it.

Cache and Performance

The plugin can keep an optional vault-local cache:

• Off: no extra cache.
• Lists only: cache list names, colors, icons, and order.
• Lists + reminders: cache full reminder contents for faster large-list loading.

List metadata can be refreshed:

• Only on full sync.
• On every refresh.
• At a configured interval.

Developer options include:

• Debug logging.
• Performance timing logs.

Requirements

• macOS.
• Obsidian desktop.
• Apple Reminders available on the same Mac.
• Reminders/Automation permission granted to Obsidian.

This plugin is desktop-only. It does not support Obsidian mobile because Apple Reminders access depends on macOS APIs.

Installation

Manual Install

1. Download the latest release from GitHub Releases.

2. Unzip the release.

3. Copy the plugin folder into your vault:

   <vault>/.obsidian/plugins/obsidian-apple-reminders-plugin/
   

4. Restart Obsidian or reload community plugins.

5. Enable Apple Reminders in Settings > Community plugins.

6. Open the plugin from the ribbon icon or command palette.

Community Plugin Install

Once accepted into Obsidian Community Plugins, install it from:

Settings > Community plugins > Browse

First Run and macOS Permissions

On first use, macOS may ask for permission. Allow Obsidian to access or control Reminders.

If reminders do not load, check:

System Settings > Privacy & Security > Reminders
System Settings > Privacy & Security > Automation

Make sure Obsidian is allowed, then restart Obsidian.

Commands

The plugin registers these commands:

• Open Apple Reminders
• Open Apple Reminders in New Tab
• Open Apple Reminders in New Window
• Load Apple Reminders now
• Full sync - Refresh lists from Reminders

Settings

General

• Sync mode: Calm, Balanced, or Live.
• Auto refresh interval: how often Balanced/Live modes check for changes.
• Default open mode: right sidebar, tab, or popout window.
• Plugin icon: Obsidian icon or bundled Apple Reminders icon.
• Startup behavior: deferred, manual, or immediate loading.

Appearance

• Default priority color mode: preset priority colors or list accent color.
• List icon style: regular or bold icons.

Sidebar

• Show or hide list counts.
• Show or hide zero counts.
• Show or hide custom list icons.
• Load list icons eagerly or lazily.

Drag and Drop

• Choose the default drop format.
• Choose embedded card style.
• Use the drop picker when set to Always Ask.
• Use Option-drop for plain text.

Linked Notes

• Set a default linked-note folder.
• Set per-list linked-note folders.
• Choose linked-note header display: banner or card.

Note Sync

• Choose sync direction:
  • Bidirectional.
  • Obsidian to Reminders only.
  • Reminders to Obsidian only.
• Choose what happens after completion:
  • Keep linked note content.
  • Remove completed linked items.

Connection to Apple Reminders

• Automatic backend selection.
• Native helper mode.
• AppleScript mode.
• Helper status and re-scan controls.
• Helper cleanup controls when installed.

Performance and Cache

• Disable cache.
• Cache list metadata only.
• Cache lists and reminder contents.
• Choose list metadata refresh behavior.
• Run full sync immediately.

Developer

• Enable debug logs.
• Enable performance measurements.
• Delete/reset plugin data.

Native Helper

The native helper is an optional Swift command-line tool that uses EventKit. It is usually faster than AppleScript for large reminder collections.

The plugin searches for the helper in this order:

<vault>/.obsidian/plugins/obsidian-apple-reminders-plugin/bin/ar-reminders-helper
~/Library/Application Support/obsidian-apple-reminders-plugin/ar-reminders-helper

Install a prebuilt helper:

1. Download ar-reminders-helper from GitHub Releases.

2. Place it in one of the supported helper locations.

3. Make it executable:

   chmod +x /path/to/ar-reminders-helper

Build the helper from source:

bash build-native-helper.sh

More detail is available in NATIVE_HELPER.md.

Local Data and Privacy

The plugin does not send reminder data to a server and does not include telemetry.

Local plugin files may include:

• data.json: plugin settings.
• cache.json: optional cache data.
• link-registry.json: reminder-to-note links.

cache.json can contain reminder titles, notes, dates, and flags if full cache mode is enabled. It is stored unencrypted inside the vault. Use Off or Lists only cache mode if you do not want reminder contents stored in vault files.

The native helper reads Reminders through EventKit and writes nothing to disk.

Troubleshooting

Reminders Do Not Load

• Confirm Obsidian has macOS Reminders permission.
• Confirm Obsidian has Automation permission for Reminders when using AppleScript.
• Restart Obsidian after changing permissions.
• Try Full sync - Refresh lists from Reminders.
• Switch backend mode to AppleScript if the native helper is missing or failing.

Native Helper Is Not Detected

• Check that ar-reminders-helper exists in one of the supported locations.
• Run chmod +x on the helper.
• Re-scan helper status from settings.
• Enable debug mode and check the developer console.

Drag and Drop Does Not Insert

• Make sure the target note is in source mode.
• Avoid dropping inside fenced code blocks.
• Avoid dropping inside Markdown tables.
• Hold Option to test plain text insertion.

Linked Notes Do Not Sync

• Check the Sync direction setting.
• Confirm the note still contains a reminder-id comment or apple-reminder block.
• Use the card refresh button or run full sync.
• If the source reminder was deleted, resolve the orphan prompt.

Development

Install dependencies:

pnpm install

Run development watchers:

npm run dev

Run tests:

npm test

Build:

npm run build

Prepare the deploy folder:

npm run deploy

Build the native helper:

bash build-native-helper.sh

Release Artifacts

A release should include:

• manifest.json
• main.js
• styles.css
• icons/
• optional bin/ar-reminders-helper

Generated files are ignored in Git and should be built for each release.

License

GPL-3.0-only. See LICENSE.