Apple Calendar (OpenClaw Plugin)

List, read, create, update, delete, and search Apple Calendar events — powered by a compiled Swift binary using EventKit for sub-second performance.

Important: First-Run Permission Requires User Interaction

You must keep your Mac unlocked and visible, ask your agent to call a calendar tool, then click Allow on the macOS Calendar permission modal.
If you do not accept that modal, the plugin will keep returning permission denied.

Why Swift + EventKit?

AppleScript calendar queries take 30+ seconds on large calendars. This plugin uses a compiled Swift binary that calls EventKit directly:

• Date-range queries use predicateForEvents (indexed) — < 100ms even with thousands of events
• UID lookups use store.event(withIdentifier:) — O(1)
• Search uses localizedCaseInsensitiveContains — native, fast, accent-aware
• The binary auto-compiles from source on first use via swiftc -O and caches itself

Requirements

• macOS (EventKit is a macOS framework)
• Swift toolchain (ships with Xcode or Xcode Command Line Tools)
• Calendar access permission (granted on first run)
• OpenClaw gateway running on macOS host (not in a container)

Installation

openclaw plugins install openclaw-apple-calendar

From source:

git clone https://github.com/androidStern-personal/openclaw-apple-calendar.git
openclaw plugins install ./openclaw-apple-calendar

Calendar Access Permission

After installing, grant calendar access to the helper app identity:

1. Restart the gateway: openclaw gateway restart (or oc-restart)
2. Keep your Mac unlocked and trigger any calendar tool (e.g., list calendars) — this compiles the helper on first use and launches calendar-helper.app
3. Accept the macOS Calendar permission modal when it appears
4. Open System Settings > Privacy & Security > Calendars
5. Find "OpenClaw Calendar" in the list and toggle it on

If needed, force explicit launch mode:

OPENCLAW_CALENDAR_HELPER_MODE=app openclaw gateway restart

Modes:

• OPENCLAW_CALENDAR_HELPER_MODE=auto (default): try app launch first, fallback to direct execution.
• OPENCLAW_CALENDAR_HELPER_MODE=app: require app launch only.
• OPENCLAW_CALENDAR_HELPER_MODE=direct: run the helper binary directly (useful for tests/headless environments).

Configuration

1. Enable the plugin

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-apple-calendar": {
        "enabled": true
      }
    }
  }
}

2. Allow for sandboxed agents

Tools are registered as optional: true and must be explicitly allowed:

{
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["group:runtime", "group:fs", "openclaw-apple-calendar"]
      }
    }
  }
}

3. Restart and verify

openclaw gateway restart
openclaw plugins list
# Should show: Apple Calendar | openclaw-apple-calendar | loaded

Tools

Tool	Description
apple_calendar_list	List all calendars with name and writable status
apple_calendar_events	List events in a date range (default: today)
apple_calendar_read	Read full event details by UID
apple_calendar_create	Create a new event in a writable calendar
apple_calendar_update	Update an existing event by UID
apple_calendar_delete	Delete an event by UID
apple_calendar_search	Search events by text (summary, location, description)

Usage Examples

List my calendars
Show me today's events
Show me the next 7 days of events with days_ahead=7
Create a meeting tomorrow at 9am on my Personal calendar called "Team Standup"
Search for "dentist" in the next 90 days
Update event UID "ABC-123" — change location to "Conference Room B"
Delete event UID "ABC-123"

Date Formats

Type	Format	Example
Timed event	YYYY-MM-DD HH:MM	2026-01-15 10:00
All-day event	YYYY-MM-DD	2026-02-01

Security

• Runs a compiled Swift binary as a local subprocess — no network calls
• Requires macOS EventKit permission (granted via system prompt on first access)
• Tools are optional: true — must be explicitly allowed in sandbox config
• Only writable calendars accept modifications (read-only calendars are protected)

Development

bun install
bun test          # run all tests

Tests create real calendar events tagged with a unique timestamp and clean them up in afterAll. No mock calendar needed.

License

MIT