Peras Skill 技能

6. Peras（Peras）

技能简介

Peras 是一款给 Claude Code 与 Codex 用的命令行扩展与菜单栏工具，用途非常具体：盯住订阅额度，预测它什么时候会烧完，并在你设定的线路上把受保护的工作停下来。0.4 版本的 CLI 与钩子完全免费、MIT 许可、全部跑在本地，不需要注册账号；macOS 13 及以上还可以安装一次性付费 4.99 欧元的原生菜单栏应用，里面住着一只叫 Clawd 的像素梨子，会在用量条上方来回走动，被暂停时就停下不动。

核心能力

1. 双平台用量监控：同时盯 Claude Code 与 Codex 的订阅用量；Codex 侧通过本地 app-server 读取 ChatGPT 套餐用量，两边的额度、历史与暂停状态彼此独立。
2. 额度消耗预测：根据最近一天的节奏或本周均值做直线预测，给出「按当前速度将在周四 14:59 用完」这类可执行结论，而不是只报一个数字。
3. 三档可配置动作：到达阈值时可选择 warn（桌面通知，智能体继续跑）、ask（下一次工具调用在 Claude Code 自带的权限弹窗里等你确认，每会话一次，开了 Remote Control 还能在手机上批）、pause（直接拒绝工具调用并给出清晰原因，本轮结束，可自动恢复或手动 peras resume）。
4. 四种阈值维度：支持百分比线（5 小时或每周，1–100 或 off）、速度线（在按当前趋势「重置前就会用完」时提前动作）、单次提问线（限制某一个 prompt 不超过本周额度的百分之多少）、时段线（例如夜间时段用满 50% 即暂停，白天保持原有阈值）。
5. 按会话分摊用量：把每周额度的上涨按各次会话的消耗比例拆开显示，同时把 claude.ai 的消耗一并计入。
6. 原生菜单栏：macOS 上以菜单栏应用形式常驻，Clawd 与 Codex 伙伴形象会随用量状态行动；也支持生成免费的 SwiftBar 菜单。
7. 状态行联动：Claude Code 的状态行会显示同样的信息，并按你设定的阈值着色。
8. 智能体可见自身预算：运行中的智能体能在自己的状态行里看到当前消耗。

安装配置

1. 命令行安装：Node 18 及以上、无运行时依赖，执行 npx peras-cli setup 完成 Claude Code 的钩子与状态行接入，执行 npx peras-cli codex setup 接入 Codex，两个可以只跑其一也可以都跑。
2. 原生应用：从 peras.vertias.eu/app 下载应用（4.99 欧元一次性），或自行构建；随后运行 npx peras-cli menubar install --native --app ~/Downloads/Peras.app 完成挂载。若偏好 SwiftBar，执行 npx peras-cli menubar install 即可获得免费菜单，命令行与钩子本身不依赖任何菜单。
3. 自行构建源码：克隆仓库的 v0.4.0 分支后按说明构建，需要 macOS 13 及以上、Node 18 及以上与 Apple 命令行工具；应用源码位于 native/ 目录，与其余部分同属 MIT 许可，购买版本可获得经 Apple 签名与公证的构建产物。
4. 状态行共存：若已经在用 ccstatusline 或自建状态行，Peras 会串联在前面并原样透传，执行 peras remove 可精确还原原配置。

使用步骤

1. 完成接入：按上面的方式安装并执行 setup 脚本，让钩子与状态行接管用量读取。
2. 查看现状：执行 peras status，它会同时列出 5 小时与每周两条用量条、重置时间、按当前速度的预测，以及当前生效的全部阈值线。
3. 设定阈值：用 peras set weekly 85 pause 设定一条线，格式是「周期（5h 或 weekly）+ 数值（1–100 或 off）+ 动作（warn / ask / pause）」；速度线、单次提问线与时段线各有对应的子命令写法。
4. 查看历史：执行 peras history 回看过去几周的峰值、越过的阈值线以及真正撞墙的时间点。
5. 恢复与调整：被 pause 拦下的任务会给出明确原因，可自动恢复或执行 peras resume 手动放行；后续随时用 peras set 改线、用 peras remove 完整卸载还原。

适用场景

• 把 Claude Code 丢给长任务后转身离开，回来发现本周额度已经被吃光；
• 希望在额度耗尽之前而不是之后被提醒；
• 多个仓库、多条会话共用同一个订阅额度，需要看清额度到底被谁花掉了；
• 夜间的无人值守任务可能跑过头，需要按时段设置更严的阈值；
• 想给单次提问设置上限，避免一次长对话吃光整周预算；
• 团队共用账号时，需要一道自动化的刹车来防止意外超支。

适用人群

重度使用 Claude Code 或 Codex 订阅的开发者与 AI 编程重度用户；用夜间与批量任务消耗额度的工作流；需要在多仓库之间分配有限额度的个人与小团队；以及希望对 AI 编程支出有明确上限感的用户。

工作原理

Peras 读取 Claude Code 已经传递给状态行的 5 小时与每周用量，并在本地保留一份小型历史；Codex 侧则通过其本地 app-server 读取 ChatGPT 套餐用量。钩子在支持的时机检查当前数值与你设定的规则，命中时执行 warn、ask 或 pause 三种动作之一，pause 会直接拒绝工具调用并终止当前轮次。预测逻辑是基于最近一次读数做直线外推，官方在「诚实的限制」一节中明确交代了边界：只对订阅额度有效，纯 API Key 会话没有可监控的订阅窗口；非交互式运行不会刷新状态行，Peras 使用的仍是最近一次交互读数，因此永远不会高估实际用量，代价是可能偏晚触发；预测本身是直线外推，一个安静的下午或一次突发都会改变结果；「按会话分摊」是估算，因为额度对整个账号只有一个总数；单次提问阈值是账号级的，同时运行的另一个会话也会被计入，因此倾向于保守暂停。

官方链接

项目仓库：https://github.com/Vertias3u/Peras ｜ 官方站点：https://peras.vertias.eu ｜ 采用 MIT 许可协议