macos-calendar-assistant

macos-calendar-assistant

Use bundled scripts for reliable Calendar.app operations.

Workflow

1. Extract title, start/end, timezone, calendar, location, notes, alarm.
2. Check conflicts before writing:
3. scripts/list_events.swift <start_iso> <end_iso>
4. Prefer idempotent writes:
5. scripts/upsert_event.py (create/update/skip)
6. Apply alarm if requested:
7. scripts/set_alarm.py --uid <event_uid> --alarm-minutes <n>
8. For hygiene, run duplicate scan:
9. 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
2. Treat the user's message bubble as primary intent.
3. Treat counterpart bubbles as constraints (availability/travel window), not direct auto-create tasks.

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

1. Time-window intent parsing
2. Phrases like "4–6 PM for the other person" should first be interpreted as an availability window.
3. Convert to a formal event only after user confirmation.

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

1. Confirmation prompt template
2. Use: "I identified X as your intent and Y as counterpart constraints. I will apply Z. Confirm?"
3. 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