# codex-panel

**Repository Path**: mingzijian/codex-panel

## Basic Information

- **Project Name**: codex-panel
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex Panel

Codex Panel 是一个极轻量的原生 macOS 菜单栏 App：显示 ChatGPT
订阅附带的 Codex 剩余额度与重置时间，并同步本机 Codex 任务动态。

## 特点

- 原生 AppKit，无 WebView、Electron 或第三方依赖
- 双层半圆仪表盘同时显示“距重置剩余时间”和“剩余额度”；7 天窗口使用
  克制的 7 个日节点，可直接比较时间进度与额度消耗速度
- “剩余额度”和“已使用”分开标注，避免把剩余百分比误读成使用量
- 窗口可自由缩放，始终保持仪表盘在上、任务卡在下的纵向阅读顺序
- 支持 45%–100% 窗口透明度，设置自动保存
- 支持“钉在桌面”，可跨桌面保持窗口置顶
- 菜单栏直接显示 `剩余百分比·活动任务数`
- macOS 26 可把 Codex Panel 添加到控制中心或直接放进菜单栏；系统卡片显示
  `剩余百分比`、`距重置时间` 与 `活动任务数`，点击即可打开完整面板
- 读取本机 Codex 任务元数据，显示运行中、等待中、已完成或失败
- 点击任务卡或菜单栏任务，可通过 `codex://threads/<任务 ID>` 定位到
  ChatGPT/Codex 桌面端的对应任务
- 常驻菜单栏；关闭窗口后继续运行，再次打开 App 可恢复窗口
- 自动刷新可选 5 / 15 / 30 / 60 分钟，默认 15 分钟
- 手动刷新至少间隔 1 分钟，请求失败后按 1 / 5 / 15 / 30 分钟退避
- 缓存上次成功结果，临时网络错误时仍能显示已有额度
- 支持多个额度桶与多个时间窗
- 不读取浏览器 Cookie，不自行保存账号或令牌
- 不读取或展示任务正文，只读取本机任务标题、生命周期标记与更新时间
- 查询时短暂调用本机 ChatGPT/Codex 的登录组件，随后立即退出

## 使用

1. 先安装并登录 ChatGPT/Codex。
2. 解压 `Codex-Panel-macOS.zip`。
3. 将 `Codex Panel.app` 拖入“应用程序”并打开。
4. App 会直接显示最紧张额度与重置时间；关闭窗口后仍会在后台监控。
5. 点击主窗口右下角齿轮，在覆盖于主窗口之上的设置抽屉中选择刷新频率、调节透明度或
   开启“钉在桌面”；设置会在下次启动时保留。
6. 再次打开 App 可重新显示窗口。若菜单栏空间足够，也可点击仪表图标
   查看全部额度。
7. macOS 26：打开控制中心编辑界面，点 `+`，搜索 `Codex Panel`，选择合适
   尺寸后添加。小尺寸主要显示图标，中/大尺寸会显示剩余额度与重置倒计时。

Codex Panel 显示的是 ChatGPT 订阅附带的 **Codex 使用额度**，不是 OpenAI API
余额，也不统计 ChatGPT 网页端各模型的消息条数。

## 构建与验证

```bash
swift run CodexPanelChecks
CODEX_PANEL_LIVE_TEST=1 swift run CodexPanelChecks
CODEX_PANEL_TASK_TEST=1 swift run CodexPanelChecks
./scripts/build-app.sh
```

App 本体要求 macOS 13 或更高版本；控制中心组件要求 macOS 26。重新构建完整
安装包时需要 Xcode 26 或更高版本，普通使用无需安装 Xcode。

为延续旧版 Quota Peek 的缓存、窗口设置和控制中心配置，工程改名后继续使用原
Bundle ID、App Group 与 Control kind；同时保留 `quotapeek://` 作为兼容 URL
Scheme，新代码使用 `codexpanel://`。