viticci/remctl

What it solves

RemCTL provides a command-line interface (CLI) for macOS Reminders, enabling power users and AI agents to programmatically manage tasks. It overcomes the limitations of standard APIs by providing fast, detailed access to the Reminders database, including support for advanced features like sections, tags, and smart lists that are often inaccessible via basic scripting.

How it works

RemCTL uses a hybrid architecture to balance speed, permissions, and system stability:

• Read Path: It performs direct SQLite reads from the local iCloud Reminders database for near-instant access to detailed metadata.
• Write Path: It uses Apple's public EventKit APIs to ensure changes sync correctly across devices.
• Private API Path: For advanced metadata (like subtasks, tags, and grocery list categorization), it optionally uses the private ReminderKit framework via an explicit --private flag.
• Capability Host: To simplify permissions, most commands are routed through a signed RemCTL Capability Host.app, which holds the necessary Full Disk Access and Automation grants, so the calling terminal or agent doesn't need them individually.

Who it’s for

• macOS Power Users: Those who want to manage their reminders via the terminal or shell scripts.
• AI Agents: Developers building agents (e.g., using Claude Code or Codex) that need a reliable way to interact with a user's task list.

Highlights

• Deep Integration: Supports sections, subtasks, tags, image attachments, and custom smart lists.
• Agent-Friendly: Provides JSON output and a structured command map for easy integration with LLMs.
• Smart List Management: Ability to create and edit custom smart lists based on priority, date, or flags.
• Grocery List Support: Native handling of grocery-specific metadata and automatic categorization.
• Flexible Scheduling: Supports natural language-like date parsing (e.g., "tomorrow 3pm", "+3d", "eod").