Agent Battery 是一款专为 macOS 设计的状态栏实用工具，旨在将 Claude Code 与 Codex 的用量监控信息，以类似“电池电量百分比”的形式直观地呈现在 Mac 右上角。
对于重度依赖 AI 编程的开发者，Claude Code 的 5 小时窗口和 7 天滚动额度规则较为复杂。在沉浸式编码时，很难实时计算剩余额度，往往直到终端弹出限流提示，才发现额度已耗尽，导致调试思路被强行中断。Agent Battery 正是为了解决这一“可见性”痛点而生。
核心功能：将 AI 额度“电量化”
安装后，该工具将常驻于 macOS 菜单栏。其核心交互逻辑如下：
- 快速预览： 状态栏直接显示当前工具的 5 小时剩余用量。
- 详细看板： 点击图标可展开弹窗，对比查看 Claude Code 与 Codex 的 5 小时额度、周额度以及具体的重置时间。
直观比喻：它就像是 AI 编程助手的“油表”。你无需在后台猜测额度，抬头看一眼状态栏，即可判断当前的额度是否足以支撑接下来的复杂问题排查。
技术原理：本地读取 vs API 抓取
与大多数需要 API Key 或访问令牌的监控看板不同，Agent Battery 放弃了网络请求方案，转而采用 本地文件读取策略。
这种设计的核心优势在于 安全性：用户无需将敏感的凭证交给第三方服务，也避免了高频请求 API 带来的网络开销与潜在的泄露风险。
数据来源与实现机制
Agent Battery 通过截取本地日志来获取实时用量，具体针对两种工具的实现方式不同：
- Codex： 直接读取本地
~/.codex/sessions/**/*.jsonl日志文件，解析最新的 rate-limit 事件，无需额外配置。 - Claude Code： 采用 Hook 机制。安装时会写入 collector 和 wrapper 脚本，并修改
~/.claude/settings.json中的statusLine.command。当 Claude Code 刷新状态行时，限额信息会被同步写入本地 JSON 文件，由 Agent Battery 读取。
安装前的关键注意事项
由于涉及本地配置修改，安装前请务必留意以下几点：
- 系统要求： 仅支持 macOS 14.0 及以上版本。
- 配置变更： 它会修改 Claude Code 的
settings.json文件。虽然程序会自动备份，但建议用户在安装前手动备份该文件。 - 运行权限： 由于应用未经过苹果签名与公证，首次启动时会被 Gatekeeper 拦截。需前往「系统设置 $rightarrow$ 隐私与安全性」中点击「仍要打开」。
- 稳定性风险： 该工具依赖于官方日志格式。如果 Claude Code 或 Codex 更新了数据输出结构，监控可能会失效，需等待作者更新。
适用场景
推荐使用人群： 已经将 Claude Code 或 Codex 深度集成到日常工作流、频繁在终端进行大规模代码重构或 Bug 排查的开发者。
不推荐人群： 仅偶尔使用网页端 AI 或轻量化使用终端 AI 的用户。该工具旨在解决“用量可见性”问题，并不能增加额度或绕过官方限制。
如果你对终端效率优化感兴趣，也可以探索更多 同类 AI 编程项目，通过工具组合提升开发体验。
项目资源
免责声明：本文基于 GitHub 公开文档整理。本站不提供侵权资源或绕过限速的引导。开源工具的稳定性及配置风险请以实际运行环境为准，建议安装前备份核心配置文件。
正文完
