Mac Reminders Agent

Integrate with macOS Reminders app to check, add, edit, delete, and complete reminders. Supports multiple reminder lists (calendars), priority levels (high/m...

Security Scan

The skill's files, install steps, and runtime instructions are consistent with a macOS Reminders integration and do not ask for unrelated credentials or hidden network access.

Purpose & Capability

Name/description align with code and assets: Node CLI, AppleScript bridge, and a Swift EventKit helper implement listing, adding, editing, deleting, and recurrence for macOS Reminders. Required runtime tools (node, Swift/Xcode CLT, applescript module) match the stated functionality.

Instruction Scope

SKILL.md and cli.js only instruct the agent to read local files (locales, optional meeting-note files) and to invoke local scripts (apple-bridge.js, eventkit-bridge.swift). All runtime actions are limited to local Reminders app access and local parsing; there are no opaque remote endpoints or instructions to exfiltrate data.

Install Mechanism

Install is just 'npm install' in the skill directory and the package pulls the 'applescript' npm package from the public registry (package-lock.json present). No external arbitrary downloads or URL-based installer stages were found.

Credentials

The skill does not request environment variables, credentials, or config paths. It does require the user to grant macOS automation/Reminders permissions (expected and necessary for functionality) and to have Swift available for native recurrence — these are proportionate to the stated purpose.

Persistence & Privilege

The skill does not request elevated platform privileges and 'always' is false. SKILL.md provides examples for creating cron jobs and a LaunchAgent to run the CLI on a schedule; these are optional user actions (not performed automatically) and should be reviewed by the user before enabling to ensure paths and scheduling match their environment.

Assessment

This skill appears to do what it claims: it runs locally on macOS, uses AppleScript and a Swift EventKit helper to access the Reminders app, and has no network exfiltration or secret-requiring behavior. Before installing: - Confirm you are on macOS and comfortable granting Terminal (or whichever host process runs the skill) automation access to Reminders and to allow the Swift helper to access Reminders. macOS will prompt for these permissions. - Review the LaunchAgent/crontab examples before copying them; they run the CLI on a schedule and reference specific node/node paths and filesystem locations that you should adjust to your machine. - If you want extra assurance, inspect reminders/eventkit-bridge.swift and reminders/apple-bridge.js (both included) — they perform local EventKit and AppleScript operations. Note: there are some minor API/implementation details in the Swift helper you can review, but nothing in the repository indicates hidden remote calls or credential collection. - If you do not want scheduled automatic runs, do not install the LaunchAgent/crontab examples. Grant permissions only when you trust the code and intend to use the skill.

Overview

This skill integrates with the local macOS Reminders app to:

• View and organize today's/this week's reminders (with unique IDs)
• Multiple lists: View all reminder lists, filter/add to specific lists
• Priority: Set and view priority levels (high/medium/low)
• Search: Find reminders by title keyword
• Add new reminders based on natural language requests
• Edit reminders: Modify title, due date, notes, priority by ID
• Delete reminders: Remove reminders by ID
• Complete reminders: Mark reminders as done by ID
• Native recurrence: Weekly, daily, monthly, yearly repeating reminders
• Parse meeting notes: Extract action items from text and suggest reminders
• Multi-language support: English, Korean, Japanese, Chinese

The skill uses the following files relative to its directory:

• cli.js (unified entry point)
• reminders/apple-bridge.js (backend: AppleScript + applescript npm module)
• reminders/eventkit-bridge.swift (native recurrence via Swift EventKit)
• reminders/meeting-parser.js (meeting notes parser for action item extraction)
• locales.json (language-specific triggers and responses)

Language Support

The skill automatically detects user language or can be explicitly set via --locale parameter.

Supported Languages

Code	Language	Example Trigger
en	English	"What do I have to do today?"
ko	한국어	"오늘 할 일 뭐 있어?"
ja	日本語	"今日のタスクは？"
zh	中文	"今天有什么任务？"

Language Detection

1. Explicit: Use --locale parameter
2. Automatic: Detect from user's message language
3. Default: Falls back to en (English)

---

How It Works

User natural language requests are handled in two cases:

1. List reminders (list)
2. Add reminder (add)

For each case, call the Node.js CLI, receive JSON results, and format them using locale-specific templates.

---

0) View Reminder Lists

Command Invocation

node skills/mac-reminders-agent/cli.js lists --locale ko

Output Format

Returns JSON with calendars array:

{
  "calendars": [
    { "id": "cal-id-1", "name": "Reminders", "isDefault": true },
    { "id": "cal-id-2", "name": "Work", "isDefault": false }
  ]
}

---

1) List Reminders

Trigger Examples (by language)

English:

• "What do I have to do today?"
• "Show me today's reminders"
• "What's on my schedule this week?"

Korean (한국어):

• "오늘 할 일 뭐 있어?"
• "오늘 미리알림 정리해줘"
• "이번 주 일정 뭐 있어?"

Japanese (日本語):

• "今日のタスクは？"
• "今日のリマインダーを見せて"

Chinese (中文):

• "今天有什么任务？"
• "显示今天的提醒"

Command Invocation

# List with default locale (en)
node skills/mac-reminders-agent/cli.js list --scope today

# List with specific locale
node skills/mac-reminders-agent/cli.js list --scope week --locale ko

# List from specific list
node skills/mac-reminders-agent/cli.js list --scope week --list "Work"

# Search by title keyword
node skills/mac-reminders-agent/cli.js list --query "meeting" --scope all

Parameters

• --scope (optional): today, week (default), all
• --list (optional): Filter by reminder list name (omit for all lists)
• --query (optional): Filter by title keyword (case-insensitive)
• --locale (optional): Response language (en, ko, ja, zh)

Output Format

Returns JSON with items array:

[
  {
    "id": "ABC-123-DEF",
    "title": "Task title",
    "due": "2026-02-05T16:30:00+09:00",
    "list": "Work",
    "priority": "high",
    "completed": false
  }
]

Response Formatting

Use locales.json templates to format responses in user's language:

English:

[Incomplete Reminders]
- 2/2 (Mon) 09:00 [Work] Meeting
- 2/3 (Tue) 14:00 [Personal] Visit bank

[Completed]
- 2/1 (Sun) [Work] Submit report ✅

Korean:

[미완료 미리알림]
- 2/2 (월) 09:00 [업무] 회의
- 2/3 (화) 14:00 [개인] 은행 방문

[완료됨]
- 2/1 (일) [업무] 보고서 제출 ✅

---

2) Add Reminder

Trigger Examples (by language)

English:

• "Add a meeting reminder for 9am tomorrow"
• "Set a reminder to submit report by Friday"

Korean (한국어):

• "내일 아침 9시에 회의 미리알림 추가해줘"
• "이번 주 금요일까지 보고서 제출 미리알림 넣어줘"

Japanese (日本語):

• "明日の朝9時に会議のリマインダーを追加して"

Chinese (中文):

• "添加明天早上9点的会议提醒"

Command Invocation

# Add with locale
node skills/mac-reminders-agent/cli.js add --title "Meeting" --due "2026-02-05T09:00:00+09:00" --locale ko

# Add with priority and specific list
node skills/mac-reminders-agent/cli.js add --title "Urgent Report" --due "2026-02-05T17:00:00+09:00" --priority high --list "Work" --locale ko

Parameters

• --title (required): Reminder title
• --due (optional): ISO 8601 format (YYYY-MM-DDTHH:mm:ss+09:00)
• --note (optional): Additional notes
• --priority (optional): high, medium, low, none (default: none)
• --list (optional): Target reminder list name (default: system default list)
• --locale (optional): Response language (en, ko, ja, zh)

Response Examples

English:

• "Added 'Meeting' reminder for 9am tomorrow."
• "Added 'Submit report' reminder without a due date."

Korean:

• "'회의' 미리알림을 추가했어요 (내일 오전 9시)."
• "'보고서 제출' 미리알림을 추가했어요 (마감일 없음)."

---

3) Edit Reminder

Trigger Examples (by language)

English:

• "Change the meeting reminder to 10am"
• "Update the report deadline to next Monday"

Korean (한국어):

• "회의 미리알림 10시로 바꿔줘"
• "보고서 마감일 다음 주 월요일로 수정해줘"

Command Invocation

# Edit title
node skills/mac-reminders-agent/cli.js edit --id "ABC123" --title "New Meeting Title" --locale ko

# Edit due date
node skills/mac-reminders-agent/cli.js edit --id "ABC123" --due "2026-03-01T10:00:00+09:00"

# Edit priority
node skills/mac-reminders-agent/cli.js edit --id "ABC123" --priority high

# Edit note
node skills/mac-reminders-agent/cli.js edit --id "ABC123" --note "Updated notes"

Parameters

• --id (required): Reminder ID (calendarItemIdentifier from list output)
• --title (optional): New title
• --due (optional): New due date in ISO 8601 format
• --note (optional): New note text
• --priority (optional): high, medium, low, none
• --locale (optional): Response language (en, ko, ja, zh)

IMPORTANT: Use list first to get reminder IDs

Before editing, always run list to get the reminder's id field. The id is an EventKit calendarItemIdentifier (UUID-like string).

---

4) Delete Reminder

Trigger Examples (by language)

English:

• "Delete the meeting reminder"

Korean (한국어):

• "회의 미리알림 삭제해줘"

Command Invocation

node skills/mac-reminders-agent/cli.js delete --id "ABC123" --locale ko

Parameters

• --id (required): Reminder ID (from list output)
• --locale (optional): Response language

---

5) Complete Reminder

Trigger Examples (by language)

English:

• "Mark the meeting reminder as done"

Korean (한국어):

• "회의 미리알림 완료 처리해줘"

Command Invocation

node skills/mac-reminders-agent/cli.js complete --id "ABC123" --locale ko

Parameters

• --id (required): Reminder ID (from list output)
• --locale (optional): Response language

---

6) Recurring Reminders (Native Recurrence)

Use --repeat to create reminders with native recurrence (single reminder with repeat rule, not multiple copies).

Command Invocation

# Weekly recurring reminder
node skills/mac-reminders-agent/cli.js add --title "Weekly standup" --due "2026-02-10T09:00:00+09:00" --repeat weekly

# Bi-weekly reminder
node skills/mac-reminders-agent/cli.js add --title "Sprint review" --due "2026-02-10T14:00:00+09:00" --repeat weekly --interval 2

# Monthly reminder until end of year
node skills/mac-reminders-agent/cli.js add --title "Monthly report" --due "2026-02-28T17:00:00+09:00" --repeat monthly --repeat-end 2026-12-31

Parameters

• --repeat (optional): daily, weekly, monthly, yearly
• --interval (optional): Repeat interval (default: 1). Example: --interval 2 = every 2 weeks
• --repeat-end (optional): End date in YYYY-MM-DD format

IMPORTANT: Always use --repeat for recurring schedules

When user requests recurring reminders (매주, 격주, 매월, etc.), MUST use --repeat option. Do NOT create multiple individual reminders manually.

Correct:

node cli.js add --title "주간 회의" --due "2026-02-10T09:00:00+09:00" --repeat weekly

Wrong (DO NOT DO THIS):

# Creating 12 separate reminders is WRONG
node cli.js add --title "주간 회의 - 2/10" --due "2026-02-10T09:00:00+09:00"
node cli.js add --title "주간 회의 - 2/17" --due "2026-02-17T09:00:00+09:00"
...

---

7) Parse Meeting Notes

Extract action items from meeting notes and suggest reminders. Pure text processing - no Reminders app access required.

Trigger Examples (by language)

English:

• "Parse my meeting notes"
• "Extract action items from this text"

Korean (한국어):

• "회의록에서 할 일 추출해줘"
• "미팅 내용에서 할 일 뽑아줘"

Japanese (日本語):

• "議事録からアクションアイテムを抽出して"

Chinese (中文):

• "从会议记录中提取行动项"

Command Invocation

# From inline text
node skills/mac-reminders-agent/cli.js parse --text "Q1 report due by March 20. John: prepare slides by Friday - URGENT" --locale en

# From a file
node skills/mac-reminders-agent/cli.js parse --file /path/to/meeting_notes.txt --locale ko

Parameters

• --text (required if no --file): Meeting notes as a string
• --file (required if no --text): Path to a text file containing meeting notes
• --locale (optional): Language for pattern matching (en, ko, ja, zh). Auto-detected if omitted.

Output Format

{
  "ok": true,
  "locale": "en",
  "labels": {},
  "items": [
    {
      "title": "Submit Q1 report",
      "due": "2026-03-20T17:00:00+09:00",
      "priority": "high",
      "confidence": "high",
      "source_line": "Q1 report due by March 20 - URGENT"
    }
  ]
}

Detected Patterns

Language	Action Keywords	Date Patterns	Priority Signals
English	TODO:, action item:, by [date], deadline:, need to	by March 20, tomorrow, next Friday	urgent, important, nice to have
Korean	~까지, ~해야, ~할 것, 담당:, 기한:	3월 15일, 내일, 다음 주	긴급, 중요, 나중에
Japanese	~まで, ~する必要, 担当:, 期限:	3月15日, 明日, 来週	緊急, 重要, できれば
Chinese	~之前, ~需要, 负责:, 截止:	3月15日, 明天, 下周	紧急, 重要, 如果可以

IMPORTANT: Recommended Claude Workflow

1. Call parse to get suggested items[]
2. Present each item to the user with title, due date, and priority
3. Ask user which items to add (all / specific ones / none)
4. For each approved item, call add --title ... --due ... --priority ...

The parse command only suggests. Claude MUST call add explicitly for each approved item. Do NOT auto-add without user confirmation.

---

Error Handling

Locale-aware Error Messages

English:

• "There was a problem accessing the Reminders app."

Korean:

• "미리알림 앱에 접근하는 데 문제가 생겼어요."

Japanese:

• "リマインダーアプリへのアクセスに問題が発生しました。"

Fallback Suggestions

When automatic integration fails, offer alternatives in user's language.

---

Requirements & Installation

System Requirements

Requirement	Details
OS	macOS only (tested on macOS 13+)
Node.js	v18.0.0 or higher
npm	Included with Node.js
Swift	Included with Xcode Command Line Tools

Installation

# 1. Install Xcode Command Line Tools (if not already installed)
xcode-select --install

# 2. Install npm dependencies
cd $SKILL_DIR
npm install

macOS Permissions

This skill requires access to the Reminders app. On first use:

1. macOS will display a permission dialog asking to allow access to Reminders
2. Click "OK" or "Allow" to grant access
3. If denied, go to System Settings > Privacy & Security > Reminders and enable access for Terminal/your IDE

Note: The Swift EventKit bridge (eventkit-bridge.swift) is compiled on-the-fly when needed. No manual compilation required.

---

Summary

• Multi-language support via locales.json (en, ko, ja, zh)
• Core commands:
  • lists [--locale XX] — view all reminder lists (calendars)
  • list --scope today|week|all [--list "NAME"] [--query "KEYWORD"] [--locale XX] — returns items with id, list, priority fields
  • add --title ... [--due ...] [--priority high|medium|low|none] [--list "NAME"] [--repeat daily|weekly|monthly|yearly] [--interval N] [--repeat-end YYYY-MM-DD] [--locale XX]
  • edit --id ID [--title ...] [--due ...] [--note ...] [--priority ...] [--locale XX]
  • delete --id ID [--locale XX]
  • complete --id ID [--locale XX]
• Multiple lists: Target specific reminder lists or search across all
• Priority: Set priority levels on reminders (high/medium/low)
• Search: Filter reminders by title keyword
• Native recurrence: Use --repeat for recurring reminders (creates single reminder with repeat rule)
• Parse meeting notes: parse --text "..." [--file path] [--locale XX] — extract action items and suggest reminders
• Automatically detect user language or use explicit --locale parameter
• Format responses using locale-specific templates