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:
   - `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
```bash
swift scripts/list_calendars.swift
```

### List events in range
```bash
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)
```bash
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)
```bash
python3 scripts/add_event.py --title "..." --start "..." --end "..."
```

### Set alarm by UID
```bash
python3 scripts/set_alarm.py --uid "EVENT_UID" --alarm-minutes 15
```

### Move event (legacy utility)
```bash
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.p...

# macos-calendar-assistant

> I use this skill to turn weekly planning, daily execution, summary, and schedule adjustment into one continuous loop.

English | [中文](#中文)

---

## English

## Why I built this skill
Before this, I built a client app called **CalendarAI**. It proved that AI-powered calendar CRUD is feasible.

I also studied a range of scheduling products, including **Toki / Calendly / Clockwise / Motion / Amie**.
Each gave me useful ideas across conversational UX, booking links, team scheduling, auto-rescheduling, and product design.

My conclusion was clear:
high-frequency, natural scheduling is not just about "creating events" — it needs to happen inside the communication tools people already use daily.

After heavily using OpenClaw, I became even more certain:
**managing schedules directly in IM conversations, then syncing into system calendar** is more agentic-friendly and more human-friendly than relying on a standalone client.

I built `macos-calendar-assistant` to close this loop:
- how weekly plans become daily blocks,
- how daily execution gets reviewed,
- and how review outcomes sync back into upcoming schedules.

So calendar is not just a record — it becomes an iterative execution system.

## How I use it
My typical workflow:
1. Create a weekly plan.
2. Use OpenClaw + AI to break it into executable time blocks.
3. Write a daily summary at the end of the day.
4. Adjust upcoming schedules directly from review results.

This creates a full loop: **plan → execute → summarize → adjust**.

## How I use it with IM
This skill works with OpenClaw across IM channels (Telegram / Discord / Feishu / iMessage / Slack).
I can say things like "add this event", "extend to 14:00", or "move to Friday night" in chat, without app switching.

If my calendar is synced via iCloud, the same schedule is visible on both **Mac Calendar** and **iPhone Calendar**.
So any event creation/update/adjustment done through OpenClaw is reflected across desktop and mobile, giv...