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