macOS Reminders
Manage Apple Reminders via $SKILL_DIR/scripts/reminders.sh. All date handling uses relative math (current date + N * days) to avoid locale issues (FR/EN/DE date formats).
Quick start
List reminder lists
Always list reminder lists first to find the correct list name:
"$SKILL_DIR/scripts/reminders.sh" list-listsCreate a reminder
echo '<json>' | "$SKILL_DIR/scripts/reminders.sh" create-reminderJSON fields:
| Field | Required | Default | Description |
|---|---|---|---|
name | yes | - | Reminder title |
list | no | default list | Reminder list name (from list-lists) |
body | no | "" | Notes/details |
offset_days | no | - | Due date as days from today (0=today, 1=tomorrow) |
iso_date | no | - | Absolute due date YYYY-MM-DD (overrides offset_days) |
hour | no | 9 | Due time hour (0-23) |
minute | no | 0 | Due time minute (0-59) |
priority | no | 0 | Priority: 0=none, 1=high, 5=medium, 9=low |
flagged | no | false | Mark as flagged |
List reminders
echo '<json>' | "$SKILL_DIR/scripts/reminders.sh" list-remindersJSON fields:
| Field | Required | Default | Description |
|---|---|---|---|
list | no | all lists | Filter by list name |
include_completed | no | false | Include completed reminders |
Interpreting natural language
Map user requests to JSON fields:
| User says | JSON |
|---|---|
| "remind me tomorrow at 2pm" | offset_days: 1, hour: 14 |
| "remind me in 3 days" | offset_days: 3 |
| "add to my shopping list" | list: "Shopping" (match closest list name) |
| "high priority" or "important" | priority: 1, flagged: true |
| "remind me on February 25 at 3:30pm" | iso_date: "2026-02-25", hour: 15, minute: 30 |
| "remind me next Monday" | Calculate offset_days from today to next Monday |
| "flag this" | flagged: true |
For "next Monday", "next Friday" etc: compute the day offset using the current date. Use date command if needed:
# Days until next Monday (1=Monday)
target=1; today=$(date +%u); echo $(( (target - today + 7) % 7 ))Example prompts
These are real user prompts and the commands you should run:
"Remind me to buy milk"
"$SKILL_DIR/scripts/reminders.sh" list-listsThen:
echo '{"name":"Buy milk","list":"Reminders"}' | "$SKILL_DIR/scripts/reminders.sh" create-reminder"Add a to-do to call the dentist tomorrow at 10am"
echo '{"name":"Call the dentist","offset_days":1,"hour":10}' | "$SKILL_DIR/scripts/reminders.sh" create-reminder"Remind me to submit the report on February 28 — high priority"
echo '{"name":"Submit the report","iso_date":"2026-02-28","hour":9,"priority":1,"flagged":true}' | "$SKILL_DIR/scripts/reminders.sh" create-reminder"Add eggs, bread, and butter to my shopping list"
echo '{"name":"Eggs","list":"Shopping"}' | "$SKILL_DIR/scripts/reminders.sh" create-reminder
echo '{"name":"Bread","list":"Shopping"}' | "$SKILL_DIR/scripts/reminders.sh" create-reminder
echo '{"name":"Butter","list":"Shopping"}' | "$SKILL_DIR/scripts/reminders.sh" create-reminder"What's on my reminders?"
echo '{}' | "$SKILL_DIR/scripts/reminders.sh" list-reminders"Show my work to-dos"
echo '{"list":"Work"}' | "$SKILL_DIR/scripts/reminders.sh" list-remindersCritical rules
- Always list reminder lists first if the user hasn't specified one — use the closest matching list name
- Never use hardcoded date strings in AppleScript — always use
offset_daysoriso_date - Confirm the list name with the user if the intended list is ambiguous
- Pass JSON via stdin — never as a CLI argument (avoids leaking data in process list)
- All fields are validated by the script (type coercion, range checks, format validation) — invalid input is rejected with an error message
- All actions are logged to
logs/reminders.logwith timestamp, command, list, and name - Due date is optional — reminders without a due date are valid (undated tasks)
- Multiple items: when the user lists several items, create one reminder per item