Pace 是一个只做一件事的 macOS 菜单栏小工具:告诉你按现在的 Claude Code 用量速度,会不会在套餐额度重置前用完;如果会,是什么时候。
第一版能用,但它的做法是从浏览器加密的 cookie 数据库里读出 sessionKey cookie,用 Keychain 里的密钥解密,再拿它去调 claude.ai 的内部用量接口。这其实是一个伪装成仪表盘的凭据处理程序。Anthropic 的服务条款写得很清楚:第三方工具不应收集、存储或转发 Claude.ai 的会话凭据,也不应借用用户的 Pro/Max OAuth token 转发请求。因此,v2 的起点不是功能列表,而是一条硬约束:
Pace 绝不能接触密码、cookie、API key 或 OAuth token,它读取的任何数据都不得离开这台 Mac。
下面的一切设计都由此展开。
1. 数据从哪里来
数据来自三个本地来源,没有任何一个是凭据。
A. claude -p "/usage" —— 权威读数
Claude Code 内置了 /usage 命令。这是一个本地命令:Claude Code 自己处理它,绝不会发给模型。以非交互方式运行时是这样的:
claude -p "/usage" --safe-mode --no-session-persistence --output-format json
在我的机器上,它大约 2.6 s 返回,其中 "num_turns": 0、"total_cost_usd": 0。Claude Code 自己完成带认证的请求;Pace 只读取 stdout。result 字段里的内容和你在交互界面里看到的一模一样:
Current session: 2% used · resets Oct 12 at 7:10pm (Australia/Sydney)
Current week (all models): 48% used · resets Oct 14 at 5pm (Australia/Sydney)
Current week (Fable): 0% used · resets Oct 14 at 5pm (Australia/Sydney)
Last 24h · 1957 requests · 10 sessions
62% of your usage was at >150k context
62% of your usage came from sessions active for 8+ hours
28% of your usage came from subagent-heavy sessions
Top subagents: general-purpose 9%
…
有几个细节是经过反复试验才调通的:
--safe-mode让探测进程不加载 hooks、MCP servers 或插件。--bare看起来很诱人,但它会完全跳过读取已保存的登录状态,因而无法报告用量。--no-session-persistence加上干净的环境变量,意味着探测不会留下任何会话记录。早期有一次测试看似留下了记录,后来查出罪魁祸首是继承了父进程的CLAUDE_CODE_CHILD_SESSION变量。现在 Pace 会从零构建子进程环境:只保留HOME、USER、TMPDIR、PATH、LANG=en_US.UTF-8、NO_COLOR=1,其余一概不传。- 工作目录。 在新文件夹里交互式运行
claude会卡在“trust this folder?”提示上。-p模式不会,但 Pace 依然会在 Application Support 下自己的空目录里运行探测,确保绝不会读到任何项目的配置。 - 解析人类可读文本。 重置时间的格式类似
resets Oct 13 at 12:09am (Australia/Sydney),有时不带日期(resets 7pm),有时不带分钟。解析器会按标注的时区解析,自动推断年份(如果算出来的日期比当前早两天以上则跨年顺延),并把已经过去的纯时间重置顺延到明天。真实输出已被收录为测试集中的 fixture。
这个数据源的代价是延迟和频率:每次读取约 2.6 s,因此 Pace 默认每隔几分钟(默认 5 分钟)跑一次,失败时采用指数退避。
B. status line —— 零成本的实时通道
Claude Code 渲染 status line 的方式,是把一段 JSON 通过管道传给你配置的命令。对于 Pro/Max 订阅用户,这段 JSON 里包含:
"rate_limits": {
"five_hour": { "used_percentage": 41, "resets_at": 1791810540 },
"seven_day": { "used_percentage": 57, "resets_at": 1791957540 }
}
它在每次回复后都会更新——而这恰好就是用量发生变化的时刻。Pace 附带了一个极小的辅助程序 pace-bridge,你可以把它串在原有的 status line 命令前面:
Claude Code ──stdin──▶ pace-bridge --chain ──stdin──▶ your status line command
│
└─▶ ~/Library/Application Support/Pace/statusline.jsonpace-bridge,同时把一份快照存到 Pace 可读的位置。这个桥接器会以原子方式写入快照,然后把相同的 stdin 传给你原本的命令,并将其输出和退出码原样透传回去,所以你的 status line 看起来分毫不差。在这台机器上,它增加的耗时小到无法测量。在 Settings(设置)中开启连接时:
- 只修改
~/.claude/settings.json中的statusLine.command键,其余键值原封不动; - 记录你原本的命令,点击 Disconnect(断开连接)即可原样恢复;
- 拒绝修改非合法 JSON 的配置文件,并保留一份一次性备份。
局限在于:rate_limits 仅对订阅用户提供,且要在 session 收到第一次回复后才会出现,同时不包含分模型周额度。因此 status line 是快速通道,而 /usage 仍是权威数据源。
实际使用中还遇到过一个意外:同时开着好几个 Claude Code session 时,每个 session 都会上报它自己最后一次回复时看到的 rate_limits。空闲的 session 会持续发送它那份更旧、更低的数字,导致读数在每次更新时在 8% 和 9% 之间来回跳动。由于同一个窗口内的用量只增不减,Pace 会把同一窗口(相同重置时间)中出现的更低读数视为滞后数据:只刷新时间戳,保留较高的数值。
C. 本地会话记录 —— 到底是什么在消耗额度
Claude Code 会把每个 session 写入 ~/.claude/projects/**/*.jsonl。Assistant 行里带有 message.usage(input、output、cache read、按 TTL 区分的 cache write)、模型名称、时间戳和工作目录。这些都不是额度百分比,但它们能告诉你 token 是什么时候、在哪个项目里花掉的。
数据量非常可观:我过去七天的记录大约有 2 GB 的 JSONL。扫描器的做法是:
- 为每个文件维护一个字节游标,只读取自上次扫描后追加的内容;
- 以 4 MB 为块读取,用
memchr查找换行符,并在付出 JSON 解码开销前先用memmem跳过不同时包含"type":"assistant"和"usage"的行; - 只处理完整的行,写了一半的行留到下一次扫描再读;
- 按
message.id+requestId去重(流式回复会把同一条消息记录多次,token 数逐次递增),只保留最大的一条。
在 release 构建下,首次扫描一周的数据大约耗时 3.5 s(约 12,000 条事件);之后的增量扫描每次只需约 12 ms,每 30 秒运行一次。
为了跨类型、跨模型比较 token,Pace 使用了一套参照 API 相对定价的加权当量:input 为 1,output 为 5,cache read 为 0.1,cache write 为 1.25(5 分钟)或 2(1 小时),再乘以模型家族系数(Haiku 为 ⅓,Sonnet 为 1,更大模型为 5⁄3)。它不需要与 Anthropic 内部的计费公式完全一致,只需要在单个窗口内成比例即可——原因就在下面的校准技巧里。
2. 把读数转化为预测
对于每个窗口(5 小时 session、周额度、分模型周额度),Pace 会计算:
| 指标 | 含义 |
|---|---|
| 匀速线(even pace) | 如果匀速消耗,现在应该走到的位置:elapsed / duration × 100 |
| 消耗速度(burn rate) | 当前每小时消耗的百分点 |
| 重置时预计用量(projected) | used + rate × hours to reset |
| 触顶时间(time to limit) | (100 − used) / rate(仅当早于重置时间时有效) |
| 可持续速度(sustainable rate) | (100 − used) / hours to reset:按这个速度花,重置时刚好用到 100% |
最关键的部分是消耗速度。如果简单粗暴地用“窗口开始以来的平均速度”,在两个方向上都会出错:当你加速时它反应迟钝,而在开局突发高消耗后又会乱报狼来了(前十分钟用掉 5%,会被线性外推成 150%)。Pace 会按优先级选用当前最可靠的估计方式:
- 校准后的本地活跃度(仅限 5 小时 session)。 用当前 session 观测到的已用百分比,除以窗口开始以来本地消耗的加权 token 总量,得出当前账号在这个窗口内每单位权重对应的百分比,再乘以过去 20 分钟的权重。由于换算系数每次都会用最新读数重新推导,权重设定上的偏差会自动抵消。Pace 要求已用额度至少达到 3% 且存在本地活动时才会采信该值。正是靠这个机制,当你启动或停掉一个重度 agent 时,消耗速度能在约 30 秒内做出反应,而不必干等下一次采样。
- 近期斜率。 对同一窗口实例的近期读数做最小二乘拟合:5 小时 session 取过去 45 分钟(跨度至少 8 分钟),周额度取过去 24 小时(跨度至少 6 小时)。如果把一小时的突发消耗外推到剩下的五天,警报就会响个不停,因此周额度必须采用更长的时间跨度。
- 窗口平均值,但仅在窗口时间已过去至少 15% 后才启用。
- 都不满足时,不显示速度。Pace 宁可不说,也不瞎猜。
读数保存在一个轻量的 JSONL 历史文件(保留 8 天)中,以窗口和重置时间作为键,因此额度重置绝不会污染斜率计算。status line 在每次回复后都会触发,所以如果数值没变,只会每 10 分钟写入一次心跳记录——既能让平缓期保持水平,又不会把文件塞满。
Dashboard 会把多个时间跨度的消耗速度(当前、1 h、5 h、24 h 和窗口平均)与可持续速度并排展示,一眼就能分清刚才只是一阵短促的高峰,还是全天持续的高消耗习惯。
提前重置与计划内重置。 额度并不总是按固定时刻重置。提前发生的周额度重置往往保留原本的计划重置时间,因此突然回落的百分比以前会被误判为滞后读数。现在,只要同一窗口内读数回落 10 个百分点以上,且一分钟或更久之后的第二次读数予以确认(或者你在手动核销一次备用重置后立即生效),Pace 就会将其认定为提前重置,消耗速度、本地校准和窗口平均值都会从这一刻起重新计算。如果官方提前预告了重置时间,可以在 Dashboard 的 Resets 卡片中添加。添加后,在该窗口内它就会成为预测的终点:预计用量、触顶时间、可持续速度、匀速线和方向箭头都会以它为目标,每张卡片还会显示到那时会有多少额度用不完。
框选任意时段进行预测。 Pace 默认的消耗速度旨在反映此时此刻。但有时你比算法更清楚接下来的安排:今晚的节奏会像今天上午那样平稳爬升,而不是像午饭后那波密集调用。在 Dashboard 的用量图表上拖动框选,或者直接选择过去 20 分钟、1 小时、2 小时或整个窗口,Pace 就会单独基于你选中的这段区间,用四种方法预测后续走势:
| 算法 | 该时段的速度算法 |
|---|---|
| 平均(Average) | 首尾读数直接相减,包含空闲时间 |
| 线性趋势(Linear trend) | 对所有读数做最小二乘拟合,斜率带 95% 置信区间 |
| 稳健趋势(Robust trend) | Theil–Sen 算法,取所有读数对斜率的中位数;单次突发消耗几乎不影响它(阴影带为中间 80% 的斜率范围) |
| 近期加权(Recent-weighted) | 半衰期为所选时段三分之一的加权最小二乘拟合,更看重时段末尾的节奏 |
趋势预测同样会遵循计划内重置,并自动忽略提前重置之前的数据。双指捏合可缩放时间轴,按住 ⌥ 双指捏合可缩放百分比轴。
3. Speed up 还是 Ease off
状态回答的是“我会不会用超?”。但你真正需要据此采取行动的问题是:“我现在该加快还是放慢?”。为此,Pace 为每个窗口计算一个数字:
factor = sustainable rate / current rate
倍率为 2 意味着你可以把速度提高到现在的两倍,到重置那一刻也才刚好用到 100%;0.5 则意味着要把速度减半。空闲时余量无限大;触顶时为 0。
- 低于 1 为 Ease off(需放缓)。这恰好就是 At risk(有触顶风险)的判定条件,因此箭头的朝向与状态颜色绝不会打架。
- 1 到 1.25 之间为 On pace(节奏正好)。正常干活时箭头保持水平不动。
- 1.25 及以上为 Speed up(可加速)。
看 session 还是看周额度? 两个窗口同时约束着你,你能跑多快取决于最紧的那个限制。因此箭头的方向跟随倍率最小的窗口。在短时密集调用期间,瓶颈通常是 5 小时 session;而如果每天的日常消耗都偏高,就算当前 session 看着很宽裕,周额度也会成为瓶颈。为了防止两个窗口倍率接近时显示来回闪烁,只有当另一个窗口比当前窗口紧至少 10% 时,主导窗口才会切换。你也可以在 Settings 中把方向固定为只看 session 或只看周额度。
如何绘制箭头。 箭头的倾角按对数刻度跟随倍率变化(4× 或 ¼× 时对应 ±60°),但加了一个小巧思。如果完全按比例绘制,×0.88 只会倾斜约 5°,在 16 pt 的菜单栏尺寸下看起来跟水平没区别——尽管这时窗口已经处于 At risk 状态了。因此,箭头在 On pace 区间内保持纯水平,一旦离开该区间就立即跳到 ±20°:这是在菜单栏尺寸下肉眼能看清箭头两翼不对称的最小倾角。
Session (5h)连续圆环:当前受限于 5 小时 session。
Week (7d)分成七段、每天一段:当前受限于周额度。
4. 全局统一的状态分级
每个窗口都会归入以下四种状态之一,菜单栏颜色、卡片和通知全都由同一个值驱动,绝不会出现口径不一的情况:
- Comfortable(充裕):预计到重置时低于 85%。
- Watch(留意):预计到重置时达到或超过 85%。
- At risk(有触顶风险):按当前速度会在重置之前用到 100%。
- Limited(已触顶):已达到额度上限。
顶部主卡片展示最吃紧的那个窗口。在所有正奔向触顶的窗口中,最早触顶的那个优先显示;否则显示预计在重置时用量最高的窗口。 只有在距离触顶足够近、需要你采取行动时(5 小时 session 剩余不到 2 h,周额度剩余不到 24 h),进入 At risk 才会触发系统通知,且每个窗口周期只提醒一次。当真正触顶,以及曾处于 At risk 或 Limited 状态的窗口重置恢复时,你也会收到通知。




5. 应用架构与界面
Pace 是一个包含三个产物的 Swift package:
- PaceCore:负责解析、探测、扫描、预测引擎与存储。不含任何 UI 代码,拥有完整的单元测试(使用 Swift Testing,测试夹具来自真实输出)。
- Pace:由 AppKit 管理
NSStatusItem与 popover,内部界面全部由 SwiftUI 绘制。采用@Observable模型,开启 Swift 6 语言模式与严格并发检查(strict concurrency)。 - pace-bridge:status line 辅助工具,打包在
Pace.app/Contents/Helpers内。
菜单栏图标 Day Ring 是完全用代码绘制的模板图像(template image)。外圈圆弧代表当前主导窗口的已用比例,内圈箭头代表节奏方向。连续圆环代表当前受限于 5 小时 session;切分为七段(每天一段)的圆环代表当前受限于周额度。平时保持单色,只有在需要你注意时才会亮起颜色;如果只想看用量圆环或只想看方向箭头,在设置里一键就能切换。
菜单栏本身是一组可自由开关和排序的显示项:最紧额度圆环、session 与周额度双环并列、任一窗口的百分比、重置倒计时、速度余量(↓0.7×),以及本周剩余 session 数。最后一项来自自动学习的换算比:一旦观测到约 20 个百分点的 session 消耗,Pace 就会通过配对历史记录中的 session 与周额度读数,算出在你的使用习惯下一个 5 小时 session 大约折合多少周额度。
按 ⌘D 打开 Dashboard 可以看到完整全局:每个窗口在不同时间跨度下的消耗速度、带有匀速线和趋势预测的窗口用量曲线、按项目和模型统计的本地活跃度,以及 Claude Code 的 /usage 给出的消耗结构诊断。
6. 把剩余额度用起来
预测不仅能告诉你什么时候会超支,也能告诉你什么时候额度会用不完。Pace 以 session 点数(即一个 5 小时 session 的百分比)为单位来核算余量,以便把 session 和周额度放在同一尺度下直接比较:当前可用余量取本个 session 与周额度预计剩余量的较小值;如果周额度的剩余超出了当前 session 能消化的上限,多出来的部分就会计入“下个 session 可用余量”(比如留到夜间跑)。
Spend 窗口(⌘E)把这些本来会白白过期的额度,转化为永远不嫌多的有益工作:把近期提交整理成文档、做快速或深度代码审查、补写缺失的测试、梳理新点子,或者运行你自定义的任务模板(recipe)。每个模板都标有大致体量(S ≈ 5、M ≈ 15、L ≈ 35 点)、执行 agent(Claude Code 或 Codex)以及 prompt 模板。选好模板和目标项目后,Pace 就会在 Herdr 中启动 agent:可以放在专门的 Pace 标签页、项目自己的标签页,或者直接发给该项目里正空闲的 agent;可以立即启动、等当前 session 重置后启动,或在你指定的时间启动。每条发出的 prompt 都带有同样的安全护栏:基于全新的 worktree 切出独立的 pace/<recipe>-<date> branch,绝不触碰别人的改动,绝不执行 merge、push、部署或向任何人发消息,写完总结即停下。你只需事后审阅这些 branch,留下有用的成果即可。


7. Pace 不做什么
- 不读取浏览器 cookie、Keychain 或 Claude Code 保存的登录凭据。
- 自己不调用任何 Anthropic 接口。网络请求由 Claude Code 按其正常机制发起。
- 不向任何地方发送任何数据。没有统计上报,没有更新检查请求。
- 不会自作主张启动 agent。Spend 必须由你点击才会运行,且任务绝不执行 merge、push 或部署。
- 非 Anthropic 出品,与 Anthropic 无关联。
如果未来 Claude Code 修改了 /usage 的输出文案导致窗口行无法解析,Pace 会明确报告“unrecognised output”,而绝不会拿过期的旧数据或编造的数字糊弄你;与此同时,status line 通道仍能继续工作。真实的命令输出已作为 fixture 纳入测试套件,一旦格式有变,就会直接体现为一个失败的测试和一处解析器修复。