项目链接：GitHub - DengyingFu/CodexMeter · GitHub

# CodexMeter

CodexMeter 是一个适用于 Windows 11 的轻量桌面悬浮窗，用来实时显示
Codex CLI 的剩余额度和重置时间。

它使用 PySide6 构建，不联网、不调用额外 API，只读取本机 Codex 会话日志。

## 功能

- 三种显示模式：展开、极简、圆环数字
- 圆环模式仅显示剩余额度，外圈同时表示剩余比例
- 深色与浅色主题，半透明 Fluent 风格界面
- 始终置顶、位置锁定、鼠标穿透和开机启动
- 自动刷新、重置倒计时和陈旧数据提示
- 支持主额度周期、第二额度周期及 Credits 信息
- 单实例运行和系统托盘控制
- 设置自动保存在本机

## 显示模式

| 模式 | 内容 |
|---|---|
| 展开 | 剩余额度、进度条、重置时间、第二额度周期和数据状态 |
| 极简 | 状态点、剩余额度、迷你进度条和倒计时 |
| 圆环数字 | 仅显示剩余额度数字，圆环表示剩余比例 |

### 展开模式

### 极简模式

### 圆环数字模式

双击悬浮窗可以按“展开 → 极简 → 圆环数字”循环切换，也可以在右键菜单或设置窗口中直接选择。

## 工作原理

CodexMeter 默认读取以下目录中的 Codex CLI 会话日志：

```text
~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
```

程序从最新的 `event_msg / token_count` 事件中解析 `rate_limits` 快照。
如果设置了 `CODEX_HOME` 环境变量，则会读取 `$CODEX_HOME/sessions`。

只有运行过 Codex 会话后才会产生额度数据；Codex 未产生新日志时，悬浮窗会继续显示最近一次快照并标记数据时间。

## 系统要求

- Windows 10/11，推荐 Windows 11
- Python 3.10 或更高版本（仅源码运行需要）
- 已使用过 Codex CLI，以便本机存在会话日志

## 从源码运行

```powershell
git clone https://github.com/DengyingFu/CodexMeter.git
cd CodexMeter
python -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txt
python main.py
```

## 构建 Windows 应用

双击 `build.bat`，或在终端中运行：

```powershell
.\build.bat
```

构建结果位于：

```text
dist\CodexMeter\CodexMeter.exe
```

PyInstaller 使用 `onedir` 模式。分发时需要复制整个 `dist\CodexMeter` 文件夹，而不只是 EXE。

## 使用方式

| 操作 | 效果 |
|---|---|
| 左键拖拽 | 移动悬浮窗并自动保存位置 |
| 双击 | 循环切换三种显示模式 |
| 右键 | 打开功能菜单 |
| 托盘图标左键 | 显示或隐藏悬浮窗 |
| 托盘图标右键 | 打开功能菜单 |

右键菜单还可以立即刷新、锁定位置、开启鼠标穿透、切换置顶状态以及退出程序。

## 配置

配置保存在：

```text
%APPDATA%\CodexMeter\settings.json
```

可配置项目包括刷新间隔、背景不透明度、低额度阈值、显示模式、主题、第二额度周期、置顶和鼠标穿透等。

开机启动使用当前用户的注册表项：

```text
HKCU\Software\Microsoft\Windows\CurrentVersion\Run
```

## 测试

```powershell
python -m pytest tests -q
```

## 项目结构

```text
CodexMeter/
├── main.py # 开发入口
├── build.bat # PyInstaller 构建脚本
├── requirements.txt
├── app/
│ ├── main.py # QApplication、单实例和系统托盘
│ ├── core/ # 设置、状态机和开机启动
│ ├── data/ # Codex 日志读取与额度解析
│ ├── ui/ # 面板、设置窗口和自定义控件
│ └── assets/ # 应用图标
├── tests/ # 单元测试
└── tools/ # 图标和调试辅助工具
```

## 隐私

CodexMeter 不会上传会话内容，也不会调用远程服务。日志只在本机读取，程序仅使用其中的额度快照字段。

## 说明

Codex CLI 日志格式可能随版本变化。如果额度长期不更新，请先确认 Codex CLI 已产生新的会话记录，然后通过右键菜单执行“立即刷新”。