--- name: calendar description: "Calendar invites and VTODO task management via CalDAV. Send/reply to invites, create/list/complete/delete todos. Syncs to Migadu CalDAV via vdirsyncer." metadata: {"clawdbot":{"emoji":"📅","requires":{"bins":["himalaya","vdirsyncer","todo"],"skills":["himalaya"]}}} --- # Calendar Send, accept, and decline calendar invitations via email. Create and manage VTODO tasks with CalDAV sync. Events and tasks sync to Migadu CalDAV via vdirsyncer. ## Testing See `TESTING.md` for dry-run and live test steps, verification checklists, and troubleshooting. ## Prerequisites - `himalaya` configured and working (see the `himalaya` skill) - `vdirsyncer` configured and syncing to `~/.openclaw/workspace/calendars/` - `todoman` (`todo`) for VTODO management (list, complete, delete) - `khal` for reading calendar (optional but recommended) - Runs via `uv run` (dependencies managed in `pyproject.toml`) ## Important: Email Sending Rules Calendar invites are outbound emails. Follow the workspace email rules: - **youlu@luyanxin.com -> mail@luyx.org**: send directly, no confirmation needed - **All other recipients**: confirm with user before sending ## Owner Auto-Attendee When sending invites, `mail@luyx.org` (owner's SimpleLogin alias) is **always added as an attendee automatically**. All invites include a **1-day reminder** (VALARM) by default. This ensures the owner receives every invite and can Accept/Decline from their own email client. No need to include it in `--to` — it's added by the script. When accepting or tentatively accepting a received invite, the original invite is **automatically forwarded to `mail@luyx.org`** so the event lands on the owner's calendar too. ## Usage All commands go through the wrapper script: ```bash SKILL_DIR=~/.openclaw/workspace/skills/calendar # Send an invite $SKILL_DIR/scripts/calendar.sh send [options] # Reply to an invite $SKILL_DIR/scripts/calendar.sh reply [options] # Manage todos $SKILL_DIR/scripts/calendar.sh todo add [options] $SKILL_DIR/scripts/calendar.sh todo list [options] $SKILL_DIR/scripts/calendar.sh todo complete [options] $SKILL_DIR/scripts/calendar.sh todo delete [options] $SKILL_DIR/scripts/calendar.sh todo check ``` --- ## Sending Invites ```bash $SKILL_DIR/scripts/calendar.sh send \ --to "friend@example.com" \ --subject "Lunch on Friday" \ --summary "Lunch at Tartine" \ --start "2026-03-20T12:00:00" \ --end "2026-03-20T13:00:00" \ --location "Tartine Bakery, SF" ``` ### Send Options | Flag | Required | Description | |-----------------|----------|------------------------------------------------| | `--to` | Yes | Recipient(s), comma-separated | | `--subject` | Yes | Email subject line | | `--summary` | Yes | Event title (shown on calendar) | | `--start` | Yes | Start time, ISO 8601 (`2026-03-20T14:00:00`) | | `--end` | Yes | End time, ISO 8601 (`2026-03-20T15:00:00`) | | `--from` | No | Sender email (default: `youlu@luyanxin.com`) | | `--timezone` | No | IANA timezone (default: `America/Los_Angeles`) | | `--location` | No | Event location | | `--description` | No | Event description / notes | | `--organizer` | No | Organizer display name (defaults to `--from`) | | `--uid` | No | Custom event UID (auto-generated if omitted) | | `--account` | No | Himalaya account name (if not default) | | `--dry-run` | No | Print ICS + MIME without sending | ### Send Examples ```bash # Simple invite (--from and --timezone default to youlu@luyanxin.com / LA) $SKILL_DIR/scripts/calendar.sh send \ --to "alice@example.com" \ --subject "Coffee Chat" \ --summary "Coffee Chat" \ --start "2026-03-25T10:00:00" \ --end "2026-03-25T10:30:00" # Multiple attendees with details $SKILL_DIR/scripts/calendar.sh send \ --to "alice@example.com, bob@example.com" \ --subject "Team Sync" \ --summary "Weekly Team Sync" \ --start "2026-03-23T09:00:00" \ --end "2026-03-23T09:30:00" \ --location "Zoom - https://zoom.us/j/123456" \ --description "Weekly check-in. Agenda: updates, blockers, action items." # Dry run $SKILL_DIR/scripts/calendar.sh send \ --to "test@example.com" \ --subject "Test" \ --summary "Test Event" \ --start "2026-04-01T15:00:00" \ --end "2026-04-01T16:00:00" \ --dry-run ``` --- ## Replying to Invites ```bash # Accept by himalaya envelope ID $SKILL_DIR/scripts/calendar.sh reply \ --envelope-id 42 \ --action accept # Decline with a comment $SKILL_DIR/scripts/calendar.sh reply \ --envelope-id 42 \ --action decline \ --comment "Sorry, I have a conflict." # From an .ics file $SKILL_DIR/scripts/calendar.sh reply \ --ics-file ~/Downloads/meeting.ics \ --action tentative ``` ### Reply Options | Flag | Required | Description | |-----------------|----------|-----------------------------------------------------| | `--action` | Yes | `accept`, `decline`, or `tentative` | | `--envelope-id` | * | Himalaya envelope ID containing the .ics attachment | | `--ics-file` | * | Path to an .ics file (alternative to `--envelope-id`) | | `--from` | No | Your email (default: `youlu@luyanxin.com`) | | `--account` | No | Himalaya account name | | `--folder` | No | Himalaya folder (default: `INBOX`) | | `--comment` | No | Optional message to include in reply | | `--dry-run` | No | Preview without sending | \* One of `--envelope-id` or `--ics-file` is required. ### Typical Workflow 1. List emails: `himalaya envelope list` 2. Read the invite: `himalaya message read 57` 3. Reply: `$SKILL_DIR/scripts/calendar.sh reply --envelope-id 57 --action accept` --- ## VTODO Tasks Manage tasks as RFC 5545 VTODO components, stored in `~/.openclaw/workspace/calendars/tasks/` and synced to CalDAV. ### Sync Model The agent's local CalDAV is the **source of truth** (no two-way sync). When a todo is created, it's saved locally and emailed to `mail@luyx.org` as a delivery copy. When the user completes a task, they tell the agent, and the agent runs `todo complete`. The daily `todo check` cron reads from local files. ### Priority Mapping (RFC 5545) | Label | `--priority` | RFC 5545 value | |--------|-------------|----------------| | 高 (high) | `high` | 1 | | 中 (medium) | `medium` | 5 (default) | | 低 (low) | `low` | 9 | ### `todo add` — Create a Todo ```bash $SKILL_DIR/scripts/calendar.sh todo add \ --summary "跟进iui保险报销" \ --due "2026-03-25" \ --priority high \ --description "确认iui费用保险报销进度" \ --alarm 1d ``` | Flag | Required | Description | |-----------------|----------|-----------------------------------------------------| | `--summary` | Yes | Todo title | | `--due` | No | Due date, YYYY-MM-DD (default: tomorrow) | | `--priority` | No | `high`, `medium`, or `low` (default: `medium`) | | `--description` | No | Notes / description | | `--alarm` | No | Reminder trigger: `1d`, `2h`, `30m` (default: `1d`) | | `--dry-run` | No | Preview ICS + email without saving | ### `todo list` — List Todos ```bash $SKILL_DIR/scripts/calendar.sh todo list # pending only $SKILL_DIR/scripts/calendar.sh todo list --all # include completed ``` ### `todo complete` — Mark as Done ```bash $SKILL_DIR/scripts/calendar.sh todo complete --uid "abc123@openclaw" $SKILL_DIR/scripts/calendar.sh todo complete --match "保险报销" ``` ### `todo delete` — Remove a Todo ```bash $SKILL_DIR/scripts/calendar.sh todo delete --uid "abc123@openclaw" $SKILL_DIR/scripts/calendar.sh todo delete --match "保险报销" ``` ### `todo check` — Daily Digest (Cron) ```bash $SKILL_DIR/scripts/calendar.sh todo check ``` Same as `todo list` but only NEEDS-ACTION items. Exits silently when no pending items. Output is designed for piping to himalaya. --- ## How It Works **Sending invites:** 1. Generates an RFC 5545 ICS file with `METHOD:REQUEST` (via `icalendar` library) 2. Builds a MIME email with a `text/calendar` attachment (via Python `email.mime`) 3. Sends via `himalaya message send` (piped through stdin) 4. Saves the event to `~/.openclaw/workspace/calendars/home/` 5. Runs `vdirsyncer sync` to push to Migadu CalDAV **Replying to invites:** 1. Extracts the `.ics` attachment from the email (via `himalaya attachment download`) 2. Parses the original event with the `icalendar` library 3. Generates a reply ICS with `METHOD:REPLY` and the correct `PARTSTAT` 4. Sends the reply to the organizer via `himalaya message send` (stdin) 5. On accept/tentative: saves event to local calendar. On decline: removes it 6. Runs `vdirsyncer sync` to push changes to Migadu CalDAV **Managing todos:** 1. `todo add`: Creates a VTODO ICS file (via `icalendar` library), saves to `calendars/tasks/`, emails to owner, syncs 2. `todo list/complete/delete/check`: Delegates to `todoman` CLI for robust RFC 5545 VTODO parsing 3. Runs `vdirsyncer sync` after mutations to push changes to Migadu CalDAV **CalDAV sync:** - Events and tasks sync to Migadu and appear on all connected devices (DAVx5, etc.) - Heartbeat runs `vdirsyncer sync` periodically as a fallback - If sync fails, it warns but doesn't block — next heartbeat catches up ## Integration with Email Processor The email processor (`scripts/email_processor/`) may classify incoming calendar invites as `reminder` or `confirmation`. When reviewing pending emails: 1. Check if the email contains a calendar invite (look for `.ics` attachment or "calendar" in subject) 2. If it does, use `reply` instead of the email processor's delete/archive/keep actions 3. The email processor handles the email lifecycle; this skill handles the calendar response ## Checking the Calendar ```bash # List upcoming events (next 7 days) khal list today 7d # List events for a specific date khal list 2026-03-25 # Check for conflicts before sending an invite khal list 2026-03-25 2026-03-26 ``` ## Timezone Reference Common IANA timezones: - `America/Los_Angeles` — Pacific (default) - `America/Denver` — Mountain - `America/Chicago` — Central - `America/New_York` — Eastern - `Asia/Shanghai` — China - `Asia/Tokyo` — Japan - `Europe/London` — UK - `UTC` — Coordinated Universal Time ## Troubleshooting **Invite shows as attachment instead of calendar event?** - Ensure the MIME part has `Content-Type: text/calendar; method=REQUEST` - Some clients require the `METHOD:REQUEST` line in the ICS body **Times are wrong?** - Double-check `--timezone` matches the intended timezone - Use ISO 8601 format: `YYYY-MM-DDTHH:MM:SS` (no timezone offset in the value) **Event not showing on phone/other devices?** - Run `vdirsyncer sync` manually to force sync - Check `~/.openclaw/workspace/logs/vdirsyncer.log` for errors - Verify the .ics file exists in `~/.openclaw/workspace/calendars/home/` **Todos not syncing?** - Check that `~/.openclaw/workspace/calendars/tasks/` exists - Verify vdirsyncer has a `cal/tasks` pair configured - Run `vdirsyncer sync` manually **Recipient doesn't see Accept/Decline?** - Gmail, Outlook, Apple Mail all support `text/calendar` method=REQUEST - Some webmail clients may vary