macOS Calendar Assistant

Manage macOS Calendar with OpenClaw in IM-first workflows (Telegram/Discord/Feishu/iMessage/Slack), including screenshot-to-schedule extraction, idempotent c...

Security Scan

The package's code and runtime instructions are consistent with a macOS Calendar assistant: it reads/writes the user's Calendar via EventKit/AppleScript, needs Calendar permission, and its install script optionally adds a cron job — nothing appears to exfiltrate data or request unrelated credentials.

Purpose & Capability

Overall the requested capabilities (reading, idempotent create/update, move, delete, alarm management, duplicate detection, cron-based daily checks) align with the skill's description. Minor mismatch: the description references "screenshot-to-schedule extraction" and IM channel integration, but the repository contains no OCR, image parsing, or direct Telegram/Discord/Slack connectors — those responsibilities appear intended for the OpenClaw agent rather than these scripts.

Instruction Scope

SKILL.md instructs the agent to run only the included scripts (list_events, upsert/add/move/delete, set_alarm, env checks, and optional installer). The scripts operate on local Calendar data and local files only; they do not call external network endpoints. They do create local files (config.json, logs, snapshot JSON) and may create notifications via osascript.

Install Mechanism

There is no remote download/install step; all code is bundled. install.sh only copies config.example.json to config.json (if missing), makes scripts executable, runs env_check.py, and writes a crontab entry. No external URLs, package registry installs, or archive extraction are used.

Credentials

The skill requests only macOS Calendar access (via EventKit / osascript) and requires Swift + Python locally — which matches its functionality. It does not require API keys or unrelated credentials. It does create and write files under user-controlled paths (skill/config.json, default output_dir in config.json, and a default OUT_DIR in calendar_clean_notify.sh like ~/clawd/memory) — this is reasonable but should be acknowledged.

Persistence & Privilege

The skill does not use always:true and does not auto-enable itself on the platform. However, install.sh will add a user crontab entry (running calendar_clean_notify.sh at the configured time) and calendar_clean_notify.sh will create a local output directory and files. Installing implies granting Calendar permission to the invoking host process. Uninstall.sh is provided to remove the cron job.

Assessment

This skill appears to do what it says: it reads and modifies your macOS Calendar using bundled Swift and AppleScript/Python scripts. Things to consider before installing: 1) It requires you to grant Calendar access to the terminal/host process — that gives the scripts full ability to read/write your events. 2) Running ./scripts/install.sh will add a user crontab entry (calendar_clean_notify.sh) and create local files/directories (config.json, logs/snapshots, default OUT_DIR such as ~/clawd/memory). Review config.example.json and edit config.json to choose output paths and notification behavior before running install. 3) If you rely on OCR/screenshot parsing or IM connectors, note those are not included here — the agent is expected to provide parsed text. 4) Inspect the AppleScript/Swift/cron lines if you want to verify exact behavior (the code includes explicit delete operations triggered only with --apply --confirm yes). 5) If you do not want periodic checks, skip running install.sh; you can still run the read/write scripts manually. If you want extra assurance, run scripts/env_check.py and the smoke/regression tests in a controlled environment first.

Use bundled scripts for reliable Calendar.app operations.

Workflow

1. Extract title, start/end, timezone, calendar, location, notes, alarm.
2. Check conflicts before writing:
   • scripts/list_events.swift <start_iso> <end_iso>
3. Prefer idempotent writes:
   • scripts/upsert_event.py (create/update/skip)
4. Apply alarm if requested:
   • scripts/set_alarm.py --uid <event_uid> --alarm-minutes <n>
5. For hygiene, run duplicate scan:
   • scripts/calendar_clean.py --start <iso> --end <iso>

Calendar routing defaults

• Workout / Run / Training → Training
• Work / Meeting / Client → Work
• Product / Development / Building → Product
• Personal / Social / Travel → Life
• If unspecified: prefer writable iCloud/CalDAV calendars over local calendars.

Note: Calendar names vary by user setup. Map the intent to the closest local calendar name before writing.

Commands

List calendars

swift scripts/list_calendars.swift

List events in range

swift scripts/list_events.swift "2026-03-06T00:00:00+08:00" "2026-03-06T23:59:59+08:00"

Output includes uid for follow-up alarm/edit operations.

Idempotent create/update (recommended)

python3 scripts/upsert_event.py \
  --title "Team sync" \
  --start "2026-03-06T19:00:00+08:00" \
  --end "2026-03-06T20:00:00+08:00" \
  --calendar "Work" \
  --notes "Agenda" \
  --location "Online" \
  --alarm-minutes 15

Result is one of: CREATED, UPDATED, SKIPPED. Use --dry-run for preview.

Legacy direct add (always creates)

python3 scripts/add_event.py --title "..." --start "..." --end "..."

Set alarm by UID

python3 scripts/set_alarm.py --uid "EVENT_UID" --alarm-minutes 15

Move event (legacy utility)

swift scripts/move_event.swift "Team sync" "Work" "2026-03-07T10:00:00+08:00" 60 --search-days 7
# optional precise match:
# --original-start "2026-03-06T10:00:00+08:00"

Prefer upsert_event.py for most rescheduling flows; use move_event.swift for direct title-based move when needed.

Duplicate scan / cleanup

python3 scripts/calendar_clean.py --start "2026-03-01T00:00:00+08:00" --end "2026-03-08T23:59:59+08:00"
python3 scripts/calendar_clean.py --start "..." --end "..." --apply --confirm yes --snapshot-out ./delete-plan.json

Upcoming events (within 2 hours)

python3 scripts/within_2h.py

Environment + tests

python3 scripts/env_check.py
python3 scripts/regression_test.py
scripts/smoke_test.sh

Daily auto-check notifier

scripts/install.sh     # run env check + install cron from config.json
scripts/uninstall.sh   # remove cron

Extraction & scheduling heuristics (from real usage)

1. Speaker ownership from chat screenshots

   • Treat the user's message bubble as primary intent.
   • Treat counterpart bubbles as constraints (availability/travel window), not direct auto-create tasks.

2. Conflict policy

   • If user explicitly says "override" (for example, "replace this slot"), allow replacing an existing slot and reschedule the displaced event.
   • If not explicit, warn and ask for a choice before overwriting.

3. Time-window intent parsing

   • Phrases like "4–6 PM for the other person" should first be interpreted as an availability window.
   • Convert to a formal event only after user confirmation.

4. Reschedule priority

   • Prefer moving flexible events (workouts/optional blocks) before strategic P0 work blocks.
   • Do not auto-move P0 items unless user explicitly requests.

5. Confirmation prompt template

   • Use: "I identified X as your intent and Y as counterpart constraints. I will apply Z. Confirm?"
   • Keep it short; avoid over-confirming when intent is explicit.

Constraints

• macOS only (EventKit + Calendar permission required)
• Default timezone comes from config.json.timezone (fallback Asia/Shanghai) when user does not specify
• Use --apply only after reviewing dry-run output