Codex Battery

A local-first usage capsule for Codex on macOS
macOS 上安静、低资源的 Codex 剩余额度胶囊

🇨🇳 中文  ·  🇬🇧 English

Created by Miyako · Local-first · Read-only

中文

Codex Battery 是一个非官方、常驻在 macOS 刘海左侧的轻量小工具。它从本机已登录的 Codex App Server 读取只读额度快照，在胶囊和浮动面板中显示 5 小时与 7 天剩余额度。

特性

• 固定胶囊入口；菜单栏空间不足时平滑收纳为图标球。
• 点击胶囊打开浮动用量面板，点击外部或收起按钮关闭。
• 支持 5 小时 + 7 天、仅 7 天、数据缺失和服务不可用等状态。
• 刷新按钮原地旋转，并显示“无法连接 Codex”“网络连接失败”“登录失效”等反馈。
• 绿色渐变进度条、精确到分钟的重置倒计时，以及浅色／深色／跟随系统主题。
• 控制台可调整胶囊宽度、系统符号图标、字体、位置微调和显示内容。

工作方式

Codex Battery.app
       │ 只读 stdio
       ▼
codex app-server --stdio
       │
       └── account/rateLimits/read

程序只读取 account/rateLimits/read，不会创建任务、发送 prompt、读取浏览器 Cookie 或上传账号信息。

快速开始

需要 macOS 13+、Swift/macOS 标准构建工具，以及已登录的 ChatGPT / Codex 桌面应用。

# 编译并安装到 ~/Applications
./scripts/install.sh

# 仅编译
./scripts/build.sh

# 生成未签名 DMG（输出到 dist/）
./scripts/package-dmg.sh

首次运行未公证的临时签名版本时，请按住 Control 点击应用并选择“打开”。自动避让菜单栏需要在“系统设置 → 隐私与安全性 → 辅助功能”允许 Codex Battery。

仓库结构

.
├── macos/                         # SwiftUI + AppKit 应用源码和运行资源
│   ├── Sources/CodexUsageNotch/
│   └── assets/
├── scripts/                       # 构建、安装、DMG 和额度读取脚本
├── plugin/codex-battery/          # 可选的 Codex 管理 Skill 插件
│   ├── .codex-plugin/plugin.json
│   └── skills/manage-codex-battery/SKILL.md
├── README.md
└── .gitignore

构建产物（.app、DMG、临时目录和本机偏好）均被忽略，不应提交到仓库。

隐私与安全

• 所有额度读取在本机完成，不上传额度或账号数据。
• 不抓取浏览器 Cookie，不读取或复制 session token。
• 额度接口是只读的，不会启动 Codex 任务或消耗使用量。
• 仓库不包含个人路径、机器码、密钥、Token、.env 或构建产物。
• 本项目为第三方工具，与 OpenAI 无隶属、赞助或官方背书关系。

许可证

当前尚未选择开源许可证。除非另行添加许可证，代码版权归 Miyako 所有，保留全部权利。

切换到 English ↑

English

Codex Battery is an unofficial, local-first companion anchored beside the macOS notch. It reads a read-only usage snapshot from the locally authenticated Codex App Server and displays five-hour and weekly remaining usage in a capsule and floating panel.

Features

• Fixed notch-side capsule with a smooth icon-ball collapse state when the menu bar is crowded.
• Floating usage panel that dismisses when clicking outside or pressing the collapse button.
• Handles five-hour + weekly, weekly-only, incomplete, and unavailable responses.
• In-place refresh animation with clear feedback for Codex, network, login, and service failures.
• Green gradient progress bars, minute-precise reset countdowns, and system/light/dark themes.
• Console controls for capsule width, system-symbol icon styles, typography, position nudges, and visible fields.

How it works

The companion only reads account/rateLimits/read over the local Codex App Server stdio channel. It does not start tasks, send prompts, read browser cookies, or upload account data.

Quick start

Requirements: macOS 13+, Swift and standard macOS build tools, and a signed-in ChatGPT / Codex desktop app.

# Build and install to ~/Applications
./scripts/install.sh

# Build only
./scripts/build.sh

# Create an unsigned DMG in dist/
./scripts/package-dmg.sh

For the first launch of this ad-hoc signed build, Control-click the app and choose Open if Gatekeeper asks. Automatic menu-bar avoidance also requires Accessibility permission.

The optional Codex management plugin lives in plugin/codex-battery/ and can be added to a local Codex setup when needed.

Repository layout

.
├── macos/                         # SwiftUI + AppKit source and runtime assets
├── scripts/                       # Build, install, DMG, and usage-reader scripts
├── plugin/codex-battery/          # Optional Codex management Skill plugin
├── README.md
└── .gitignore

Generated .app bundles, DMGs, temporary files, local preferences, credentials, machine identifiers, and personal assets are intentionally excluded.

Privacy and security

Codex Battery is local-first: no usage or account data is uploaded; browser cookies, Codex databases, and session tokens are not read or copied; the usage endpoint is read-only and does not consume Codex usage. It is not affiliated with or endorsed by OpenAI.

License

No open-source license has been selected yet. Unless a license is added, the source is copyright © 2026 Miyako and all rights are reserved.

切换到中文 ↓

_{Windows 平台目前正在开发中 / The Windows platform is currently under development.}