An Apple Reminders CLI for power users and AI agents. RemCTL supports all the latest Reminders features such as sections, subtasks, tags, rich links, groceries lists, templates, smart lists, and image attachments. (Not affiliated with Apple.)

RemCTL – 从命令行和 AI 工具控制 Apple Reminders

功能概述（通俗解释）

RemCTL 是一款 macOS 专用工具，可让您无需打开 Reminders 应用即可读取和编辑 Apple Reminders。提供以下功能：

终端 CLI（remctl …）— 用于列出、添加、完成、搜索和管理提醒事项、列表、截止日期、优先级等。
MCP（Model-Context-Protocol）服务器 — 使 Claude Desktop、Claude Code 或任何其他 MCP 兼容应用等 AI 助手能够以编程方式调用相同命令。
Claude Code 和 Codex 插件 — 直接在这些 AI 编码环境中嵌入提醒事项工作区，显示“今日”栏和交互式窗格。
访问 Apple 私有 ReminderKit 功能（分区、标签、子任务、智能列表、模板等）— 通过传递 --private 标志启用。

所有操作都通过一个名为 RemCTL Capability Host 的小型签名后台应用进行，该应用持有 macOS 权限（提醒事项、自动化、完全磁盘访问）。一旦该主机获得授权，CLI、脚本和 AI 工具无需自身权限即可操作。

适用人群

高级用户 — 偏好使用 shell 式工作流进行任务管理。
开发者 — 构建需要操作提醒事项的自动化或脚本。
AI 助手开发者 — 希望其代理（Claude、Hermes 等）通过标准 MCP 接口读写用户提醒事项。
Mac 生产力爱好者 — 希望将提醒事项集成到 Claude Code 或 Codex 工作区。

获取方式

下载 — 从 GitHub Releases 页面下载已签名的 DMG（RemCTL-arm64.dmg），运行“Install RemCTL”应用。它会安装 Capability Host、私有 Python 运行时，并将 remctl 二进制文件添加到 PATH。
从源代码构建（Intel Mac 必需）— 安装 Apple 的命令行工具，克隆仓库，并运行 ./install.sh --from-source --bootstrap。该脚本会创建本地签名证书，使主机应用在更新后仍能保持权限。

两种方法都会要求输入一次 macOS 密码并设置所需权限。

核心命令（快速速查表）

remctl today                     # 显示今日到期或已逾期任务
remctl upcoming 7                # 未来 7 天内到期的任务
remctl add "Review PR" -l Work -d "tomorrow 10:00" -p high
remctl done 23880                # 将一个或多个 ID 标记为已完成（最多 50 个）
remctl search "invoice" --json # 为编程使用输出 JSON
remctl info 23880 --json         # 转储提醒事项的所有存储字段

所有命令都支持 --json 输出，便于机器读取，别名 rctl / reminders 也能同样工作。

通过 MCP 进行 AI 集成

remctl mcp install 在 Mac 上所有受支持的 AI 应用中注册 MCP 服务器。
可以指定特定客户端，例如 remctl mcp install --client claude-desktop。
安装后，AI 助手可以调用 mcp__remctl__add、mcp__remctl__search 等工具，甚至可以在 AI UI 中显示交互式 提醒小部件。
服务器可以通过私有 Tailscale 网络公开，供远程 Claude Code 或 Codex 实例使用（--client tailscale）。

Claude Code 插件亮点

提示框上方的**“今日”栏** — 显示计数、逾期项目以及即将到期的任务列表。
/reminders 窗格 — 在 Claude Code 内显示完整的提醒事项 UI（列表、列、日历布局）。
通过 JSON 设置进行可配置显示（band、compact、status、pane only）。
实时更新：栏在 RemCTL 驱动的更改后或每隔几分钟自动刷新。

Codex 插件亮点

Codex 侧边栏中的完整提醒事项工作区 — 镜像原生应用的外观（图标、颜色、浅色/深色模式）。
拖放、检查器面板、命令面板和自定义布局（列表、列、日历）。

私有元数据支持

RemCTL 可以通过添加 --private 标志来写入 Apple 未公开的字段（分区、标签、子任务等）。它使用 Apple 的内部 ReminderKit 框架，因此这些功能可能会在未来的 macOS 版本中失效。文档列出了当前可用的私有键。

代理就绪功能

确定性日期格式（YYYY-MM-DD 或 YYYY-MM-DD HH:MM）。
remctl doctor --for-agent --json 报告就绪状态；access.effective 字段指示 Capability Host 是否具有所需权限。
代理应使用 remctl info <id> --json 验证写入操作。

更新与卸载

升级 — 下载新的 DMG 或拉取最新源代码并重新运行 install.sh。保持相同的签名证书可保留现有权限。
卸载 — 使用捆绑脚本或 ./uninstall.sh。您可以选择保留配置（--keep-config）或进行试运行以查看将删除的内容。

文档与结构

文档位于 docs/ 文件夹（安装、命令指南、MCP、插件、私有元数据、架构等）。
核心源文件在 README 的 Project layout 表中明确列出。
许可证：MIT。

总结： RemCTL 是 Apple Reminders 与命令行/脚本工作流以及现代 AI 助手之间的真正全功能桥梁，专为 macOS 14+ 构建。

viticci/remctl