RemCTL – Control Apple Reminders from the command line and AI tools

What it does (in plain language)

RemCTL is a macOS‑only utility that lets you read and edit Apple Reminders without opening the Reminders app. It provides:

• A terminal CLI (remctl …) for listing, adding, completing, searching and managing reminders, lists, due dates, priorities, etc.
• An MCP (Model‑Context‑Protocol) server so AI assistants such as Claude Desktop, Claude Code, or any other MCP‑compatible app can call the same commands programmatically.
• Claude Code and Codex plugins that embed a Reminders workspace directly inside those AI coding environments, showing a “Today” band and an interactive pane.
• Access to Apple‑private ReminderKit features (sections, tags, subtasks, smart lists, templates, etc.) when you pass the --private flag.

All operations go through a tiny signed background app called RemCTL Capability Host, which holds the macOS permissions (Reminders, Automation, Full‑Disk Access). Once that host is authorized, the CLI, scripts, and AI tools can act without needing their own permissions.

Who might use it

• Power users who prefer a shell‑oriented workflow for task management.
• Developers building automations or scripts that need to manipulate Reminders.
• AI‑assistant developers who want their agents (Claude, Hermes, etc.) to read/write a user’s Reminders via a standard MCP interface.
• Mac‑centric productivity enthusiasts who want Reminders integrated into Claude Code or Codex workspaces.

How to get it

1. Download the signed DMG (RemCTL-arm64.dmg) from the GitHub Releases page and run the “Install RemCTL” app. It installs the Capability Host, a private Python runtime, and adds the remctl binary to your PATH.
2. Build from source (required for Intel Macs) by installing Apple’s Command‑Line Tools, cloning the repo, and running ./install.sh --from-source --bootstrap. The script creates a local signing certificate so the host app can keep its permissions across updates.

Both methods ask for your macOS password once and set up the required permissions.

Core commands (quick cheat‑sheet)

remctl today                     # show tasks due today or overdue
remctl upcoming 7                # tasks due in the next 7 days
remctl add "Review PR" -l Work -d "tomorrow 10:00" -p high
remctl done 23880                # mark one or many IDs as completed (max 50)
remctl search "invoice" --json # JSON output for programmatic use
remctl info 23880 --json         # dump all stored fields for a reminder

All commands support --json for machine‑readable output, and aliases rctl / reminders work the same.

AI integration via MCP

• remctl mcp install registers the MCP server with every supported AI app on the Mac.
• You can target a specific client, e.g. remctl mcp install --client claude-desktop.
• Once installed, AI assistants can call tools like mcp__remctl__add, mcp__remctl__search, etc., and even display an interactive reminders widget inside the AI UI.
• The server can be exposed over a private Tailscale network for remote Claude Code or Codex instances (--client tailscale).

Claude Code plugin highlights

• “Today” band above the prompt showing counts, overdue items, and a short list of upcoming tasks.
• /reminders pane with full Reminders UI (list, column, calendar layouts) inside Claude Code.
• Configurable display (band, compact, status, pane only) via JSON settings.
• Live updates: the band refreshes automatically after any RemCTL‑driven change or every few minutes.

Codex plugin highlights

• A complete Reminders workspace inside the Codex sidebar, mirroring the native app’s look (icons, colors, light/dark mode).
• Drag‑and‑drop, inspector panel, command palette, and custom layouts (list, column, calendar).

Private‑metadata support

RemCTL can write fields that Apple does not expose publicly (sections, tags, subtasks, etc.) when you add the --private flag. It uses Apple’s internal ReminderKit framework, so these features may break with future macOS releases. The docs list which private keys are currently functional.

Agent‑ready features

• Deterministic date formats (YYYY‑MM‑DD or YYYY‑MM‑DD HH:MM).
• remctl doctor --for-agent --json reports readiness; the access.effective field indicates whether the Capability Host has the needed permissions.
• Agents should verify writes with remctl info <id> --json.

Updating & uninstalling

• Upgrade by downloading the new DMG or pulling the latest source and rerunning install.sh. Keeping the same signing certificate preserves existing permissions.
• Uninstall via the bundled script or ./uninstall.sh. You can keep your config (--keep-config) or do a dry‑run to see what would be removed.

Documentation & structure

• Docs live in the docs/ folder (installation, command guide, MCP, plugins, private metadata, architecture, etc.).
• Core source files are clearly listed in the README’s Project layout table.
• License: MIT.

---

Bottom line: RemCTL is a genuine, full‑featured bridge between Apple Reminders and both command‑line / script workflows and modern AI assistants, built specifically for macOS 14+.