Apple Reminders

Harness-agent tools

Concept	Tool
Shell / brew / remindctl	execute
Memory (agent-only notes, no phone sync)	memory_store, memory_recall

Builtin skill path: /_builtin_skills/apple-reminders/.

Use remindctl to manage Apple Reminders from the terminal. Tasks sync across all Apple devices via iCloud.

Bootstrap (run before first use)

Do not call remindctl until this checklist passes. Install missing deps yourself via execute — do not ask the user to run brew unless install fails or Homebrew is missing.

1. Confirm macOS

uname -s

Expect Darwin. On Linux/Windows, stop and tell the user this skill is macOS-only.

2. Check / install remindctl

command -v remindctl && remindctl --version

If missing:

command -v brew
brew install steipete/tap/remindctl
remindctl --version

If brew is not installed, explain that Homebrew is required and point to https://brew.sh — do not guess alternative install paths.

3. Check / request Reminders permission

remindctl status

If output indicates missing authorization:

remindctl authorize

Then tell the user to approve Reminders access in the system prompt or System Settings → Privacy & Security → Reminders. Do not retry in a tight loop — wait for the user to confirm they approved.

4. Smoke test

remindctl list

If this succeeds, proceed with the user's task.

When to Use

• User mentions "reminder" or "Reminders app"
• Creating personal to-dos with due dates that sync to iOS
• Managing Apple Reminders lists
• User wants tasks to appear on their iPhone/iPad

When NOT to Use

• Agent-only "remind me later" without phone sync → memory_store or ask the user to set up OS cron / an external scheduler
• Calendar events → Apple Calendar or Google Calendar
• Project task management → GitHub Issues, Notion, etc.
• If user says "remind me" but means an in-chat nudge → clarify first

Quick Reference

View Reminders

remindctl                    # Today's reminders
remindctl today              # Today
remindctl tomorrow           # Tomorrow
remindctl week               # This week
remindctl overdue            # Past due
remindctl all                # Everything
remindctl 2026-01-04         # Specific date

Manage Lists

remindctl list               # List all lists
remindctl list Work          # Show specific list
remindctl list Projects --create    # Create list
remindctl list Work --delete        # Delete list

Create Reminders

Always confirm title and due date with the user before add.

remindctl add "Buy milk"
remindctl add --title "Call mom" --list Personal --due tomorrow
remindctl add --title "Meeting prep" --due "2026-02-15 09:00"

Due Time vs Alarm / Early Nudge

--due and --alarm are different fields:

• --due sets the reminder's due date/time.
• --alarm sets the EventKit alarm/notification trigger. Pass --alarm explicitly when the user asks for an earlier nudge.

Example — due 2:00 PM, notify 30 minutes early:

remindctl add --title "Hairdresser" --due "2026-05-15 14:00" --alarm "2026-05-15 13:30"

Edit an existing reminder:

remindctl edit 87354 --due "2026-05-15 14:00" --alarm "2026-05-15 13:30"

Verify with JSON (UI may group by alarm time):

remindctl today --json

Expected fields: dueDate (due time), alarmDate (notification time).

Complete / Delete

remindctl complete 1 2 3          # Complete by ID
remindctl delete 4A83 --force     # Delete by ID

Output Formats

remindctl today --json       # JSON for scripting
remindctl today --plain      # TSV format
remindctl today --quiet      # Counts only

Prefer --json when parsing output programmatically.

Date Formats

Accepted by --due and date filters:

• today, tomorrow, yesterday
• YYYY-MM-DD
• YYYY-MM-DD HH:mm
• ISO 8601 (2026-01-04T12:34:56Z)

Rules

1. "Remind me" — clarify: Apple Reminders (syncs to phone) vs memory_store / external schedule
2. Always confirm reminder content and due date before creating
3. Run the Bootstrap section when remindctl fails or on first use in a session
4. Use --json for programmatic parsing