⚡ cc-prewarm

English | 中文

📖 项目主页 →

让 Claude Code / Codex 的 5 小时额度窗口在你工作时段中间重置,而不是在工作开始时才计时——高峰期可以横跨 两个 窗口,缓解额度紧张。

零依赖,纯本地分析,同时支持 Claude Code 和 Codex。

原理

Claude Code 和 Codex 都按 5 小时滚动窗口 计额度。这个计时器有两个关键特性:

1. 从你发第一条消息时才开始计时;
2. 窗口到期后 不会自动重启——要等你下一条消息才开启新窗口。

举例:你的高峰是 09:00–13:00,如果 09:00 才开始用,窗口跑 09:00→14:00,整段高峰只覆盖 一个 窗口。

但如果你提前在 06:00 发一条无关紧要的消息,窗口在 11:00 就重置了——正好落在高峰中间。于是 09:00–13:00 横跨两个窗口,在高峰最紧张的时段能多拿一个新窗口的额度。这是缓解高峰额度紧张,不是字面意义上"所有事都翻倍"。

cc-prewarm 把这件事自动化:读取你本地的使用记录,算出你真实的高峰时段,然后每天定时发一条极短的"预热"消息,让窗口重置点卡在最有用的位置。

安装

需要 Node.js ≥ 18。

npm install -g cc-prewarm
cc-prewarm                # 启动设置向导

不想全局安装,临时跑一次:

npx cc-prewarm

从源码用(开发/调试):

git clone https://github.com/9961405-lab/cc-prewarm.git
cd cc-prewarm
node bin/cli.js

快速开始:傻瓜式向导

直接运行,跟着 3 步走完就配好了:

cc-prewarm

向导会:

1. 扫描本地数据——分别分析 Claude Code 和 Codex 的使用习惯,画出 24 小时分布图,算出各自高峰;
2. 确认设置——自动检测你装了哪个/哪些工具,为每个工具分别推荐触发时间(可改);
3. 安装定时任务——写入系统定时任务,可选立即测试一次。

两个工具的额度窗口 相互独立,所以各自有独立的触发时间(例如 Claude 06:00、Codex 17:00)。

命令

cc-prewarm              # 交互式设置向导(推荐)
cc-prewarm analyze      # 分析使用习惯,推荐触发时间(分工具 + 综合)
cc-prewarm install      # 安装定时预热任务(自动固化到 ~/.cc-prewarm/app)
cc-prewarm trigger      # 立即发一条预热消息
cc-prewarm status       # 窗口状态 + 置信度 + 最近 7 天成功率
cc-prewarm doctor       # 体检:node、claude、codex、定时任务、pmset 唤醒
cc-prewarm logs         # 查看 ~/.cc-prewarm.log 最近若干行
cc-prewarm history      # 最近触发记录 + 失败原因聚合
cc-prewarm uninstall    # 移除定时任务

# 常用选项
--agent=claude|codex    指定工具(默认 claude)
--hour=N                指定触发时间(0-23,覆盖自动推荐)
--lead=N                提前于高峰几小时触发(默认 3)
--dry-run               仅预览将执行的操作,不实际安装

analyze 示例

  ⚡ Claude Code 使用画像
  938 条事件,跨 4 天  (/Users/you/.claude/telemetry)

  09:00   92  ██████████████  ◀ 高峰
  10:00  115  ██████████████████  ◀ 高峰
  11:00  104  ████████████████  ◀ 高峰
  12:00  209  ████████████████████████████████  ◀ 高峰
  ...

  高峰时段:   09:00–13:00 (55% 集中)
  建议触发:   06:00 (提前 3h → 1 → 2 窗口,2.0×)

  ⚡ Codex 使用画像
  ...各自独立分析...

  ⚡ 最终推荐
  触发时间:   06:00 (提前 3h → 窗口在高峰中间重置)
  窗口数量:   1 → 2 个窗口覆盖高峰  (2.0× 提升)

它是怎么定时的

| 系统 | 机制 | |------|------| | macOS | ~/Library/LaunchAgents 下的 LaunchAgent plist(重启后仍生效),每个工具一个 | | Linux | 打印一条 crontab 行让你添加 | | Windows | 打印一条 schtasks 命令让你运行 |

定时任务调用 cc-prewarm trigger,它会发一条极短的无头消息(claude -p 或 codex exec --skip-git-repo-check --sandbox read-only)来开启窗口。

⚠️ macOS:只对清晨触发的人重要

launchd 定时任务 不会叫醒睡眠中的 Mac。如果你最早一次触发在凌晨/清晨(机器还在睡觉的时段),预热就不会准点触发,失去意义。白天本来就开着机的话,完全不用做这一步。

把"最早一次触发时间减 2 分钟"填进下面命令:

sudo pmset repeat wakeorpoweron MTWRFSU HH:MM:00

举例:

| 你的最早触发时间 | 命令 | |---|---| | 06:00 | sudo pmset repeat wakeorpoweron MTWRFSU 05:58:00 | | 08:00 | sudo pmset repeat wakeorpoweron MTWRFSU 07:58:00 | | 14:00(白天) | 不用设——下午机器肯定开着 |

不知道自己设的是几点?跑 cc-prewarm doctor 会直接告诉你需要的命令。改系统电源设置需要管理员密码。

可观测性

• 带时间戳的日志:每次触发都往 ~/.cc-prewarm.log 写一行带日期时间的结果,cat 一下就知道每天有没有准点跑、成没成功。
• 最近结果:cc-prewarm status 显示每个工具最近一次预热的时间和结果。
• 失败通知:定时任务失败(登录过期 / 撞额度上限 / 二进制丢失)会弹 macOS 系统通知。
• 健康自检:status 会校验定时任务依赖的 node 路径是否还在,失效则红字告警。

预热自己产生的活动会被记录在 ~/.cc-prewarm/history.jsonl,并在分析时 自动剔除,避免工具的 ping 把推荐时间越带越偏。

隐私

cc-prewarm 只读取本地使用记录里的时间戳——

• Claude Code: ~/.claude/telemetry/*.json
• Codex: ~/.codex/sessions/**/*.jsonl

从不读取消息内容,也从不把任何东西传出你的电脑。 status 里的窗口重置估算是本地算出来的尽力而为值,不是实时账单数据。

局限

这套玩法依赖目前额度窗口的计量方式。如果 Anthropic 或 OpenAI 改了规则(比如改成按自然日重置、或任意一条消息都重置),这个技巧就失效了。它是个聪明的取巧,不是保证。

预热消息本身也会消耗一点点额度——这正是它能开启窗口的原因。

License

MIT