Codex macOS Planner

一套面向 macOS 的开源 AI 目标与日程系统：让 Codex 通过自然语言管理本地日程、近期任务、长期目标和截止日期，并通过屏幕边缘与刘海随时查看。

English · 安装指南 · 安全与隐私

解决什么问题

普通日历适合回答“几点要去哪里”，却不擅长推动长期目标；普通待办工具又容易堆满没有截止日期的愿望清单。本项目将两者明确分工：

• Quiet Tasks 日程：课程、学习时间块、会议和活动；
• Quiet Tasks：今天要做的事、近期安排、长期目标拆出的阶段任务，以及逐项截止日期；
• Apple Calendar / Reminders：可选兼容层，不再作为默认写入目标；
• Codex：读取现有安排、发现冲突、拆解模糊目标、建议截止日期，并在确认后写入；
• 桌面小组件：持续显示未完成任务，完成一项就勾选一项。

架构

flowchart LR
    U[自然语言目标] --> C[Codex]
    C -->|当天与本周时间块| Q[quiet-tasks-cli]
    Q --> S[本地 schedule.json]
    Q --> J[本地 tasks.json]
    S --> L[左侧潮汐时间线]
    J --> N[刘海任务岛]
    N -->|勾选完成| J

Loading

核心原则

1. 本地日程只承载具有明确开始与结束时间的安排。
2. 模糊目标必须拆成可执行、可勾选、带截止日期的任务。
3. 写入前先读取现有本地日程和任务，避免重复与时间冲突。
4. 截止日期使用结构化字段，不重复写进标题。
5. 只置顶当前最重要的少量任务，避免“全部重要”等于没有重点。
6. 完成使用勾选；删除、批量改期和批量完成必须再次确认。
7. 每次任务写入前自动备份，所有数据默认留在本机。

快速开始

1. 安装依赖

brew tap schappim/ekctl
brew install ekctl

npx -y mcp-server-apple-events@1.5.0

Quiet Tasks 可使用项目提供的审慎安装脚本从上游 v0.4.0 源码本地构建：

./scripts/install-quiet-tasks.sh

2. 接入 Codex

将 config/codex-mcp.toml.example 中的配置增量合并到 ~/.codex/config.toml。不要覆盖已有模型、代理、权限或其他 MCP 配置。

codex mcp list

3. 安装本地任务适配命令

./scripts/install-cli.sh
quiet-tasks-cli list

# 读取本地日程
quiet-tasks-cli schedule-list --from "2026-08-26" --to "2026-09-01"

4. 添加桌面小组件

首次打开 Quiet Tasks 后：

1. 在 macOS 桌面空白处右键；
2. 选择“编辑小组件”；
3. 搜索 Quiet Tasks；
4. 添加大号或中号小组件；
5. 把它放在壁纸留白区。

详细步骤、权限处理和验证命令见安装指南。

常用命令

# 读取所有未完成任务
quiet-tasks-cli list

# 创建有截止日期的高优先级任务
quiet-tasks-cli add \
  --title "完成第一阶段英语复习" \
  --due "2026-09-01 20:00" \
  --priority high \
  --pin

# 完成任务
quiet-tasks-cli complete --title "完成第一阶段英语复习"

# 创建本地日程（自动检查重复和时间冲突）
quiet-tasks-cli schedule-add \
  --title "英语学习" \
  --start "2026-08-26 08:15" \
  --end "2026-08-26 09:15"

仓库内容

• docs/installation.md：安装、权限和端到端验证；
• docs/planning-rules.md：目标拆解、优先级与写入规则；
• docs/architecture-decisions.md：为什么采用这套分工；
• scripts/quiet-tasks-cli：无依赖的本地任务读写适配；
• templates/AGENTS.md：可复制到个人工作区的 Codex 规则；
• config/codex-mcp.toml.example：增量 MCP 配置示例。

上游项目

本项目不复制上游源代码，只提供集成、规则和本地适配：

• mcp-server-apple-events（MIT）
• ekctl
• Quiet Tasks（MIT）

兼容性说明

• 目标平台：Apple Silicon Mac；
• Quiet Tasks 要求 macOS 14 或更高版本及 Xcode；
• Apple Events MCP 1.5.0 的闹钟、重复规则、位置触发器仍为只读字段，因此写入这些字段时使用 ekctl；
• quiet-tasks-cli 分别管理 tasks.json 与 schedule.json，并在修改前自动备份；
• 未经用户确认，不执行全局 tccutil reset Calendar 或 tccutil reset Reminders。

License

MIT