# CodexNotch-Windows

**Repository Path**: mariosofa/codex-notch-windows

## Basic Information

- **Project Name**: CodexNotch-Windows
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-24
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# CodexNotch

<img src="Resources/AppIcon.svg" width="240" alt="CodexNotch 应用图标">

### Codex 额度，始终在眼前。

**把周额度、5 小时额度明细、精确重置时间和任务状态，固定在 MacBook 刘海旁。**<br>
切到浏览器、IDE 或任何其他应用，额度仍然一眼可见。

[![macOS 14+](https://img.shields.io/badge/macOS-14%2B-111111?logo=apple)](https://github.com/fengdwx/codex-notch/releases/latest)
[![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)](Package.swift)
[![Latest release](https://img.shields.io/github/v/release/fengdwx/codex-notch?label=下载最新版&color=2ea44f)](https://github.com/fengdwx/codex-notch/releases/latest)
[![MIT License](https://img.shields.io/badge/License-MIT-4c8bf5)](LICENSE)
[![LINUX DO](https://img.shields.io/badge/LINUX-DO-FFB003.svg)](https://linux.do)

[**下载最新版**](https://github.com/fengdwx/codex-notch/releases/latest) · [**观看 26 秒中文演示**](docs/assets/codex-notch-demo-zh.mp4) · [English](README.md)

</div>

[![CodexNotch 中文产品演示](docs/assets/codex-notch-demo-zh-animated.gif)](docs/assets/codex-notch-demo-zh.mp4)

<p align="center"><sub>真实 App 演示：周额度、精确重置时间、全部重置额度到期时间、跨应用持续可见，以及任务运行状态。</sub></p>

**项目来源与修改：**本项目主要参照 [fengdwx/codex-notch](https://github.com/fengdwx/codex-notch) 修改，新增了原生 Windows 顶部悬浮条，以及 Tibo（@thsottiaux）推文中的 Codex 重置公告检测与展示。公告通过 [Codex Resets](https://codex-resets.com/zh-CN) 提供的公开数据获取，并非直接抓取 X/Twitter；公告不代表个人账户额度已到账。

**Windows 版本：**悬浮条可显示账户额度、任务状态和上述重置公告。构建与使用方法见 [Windows 说明](Windows/README.zh-CN.md)。现有下载页提供的是 macOS 版本。

## 0.2.2 更新

- 支持登录时自动启动，以及关闭左侧显示，减少菜单栏遮挡。
- 设置分为“通用”“外观”“浮动横条”，说明更加简洁清晰。
- 无需连接外接屏幕，即可预览浮动横条样式和任务状态。
- 动画开关独立于系统“减少动态效果”；关闭动画可减少开销，额度和任务状态照常更新。
- 修复设置窗口重复激活可能导致下拉菜单无法正常选择的问题。

## 0.2.1 更新

- 设置窗口已打开时，再次点击设置会将它带到前面。
- 在应用内下载、校验、安装更新并重启。从旧版本升级时，请先手动安装一次 0.2.1。

## 0.2.0 更新

- 悬停时轻微预撑，展开后带一点回弹，收回过渡更连贯。
- 优化字体层级和留白，文字在展开与收回时保持自然大小。
- 浮动条中间支持个人签名、轨道签名、运行计时和细流光四种样式；紧凑浮动条可见且启用动画时，签名流光持续运动。
- 优化浮动条状态图标的视觉平衡，显示 Codex 最新任务名称，过滤标题中的附件说明，修正转义字符显示。

## 为什么做 CodexNotch

Codex 的额度很容易被其他窗口挡住。CodexNotch 把最关心的三个答案固定在 MacBook 刘海旁：

- **周额度还剩多少，5 小时额度明细是多少？**
- **到底几点几分几秒重置？**
- **任务现在还在运行吗？**

无论你在写代码、查资料还是处理其他工作，都不用切回 Codex 查看。

> **看一眼刘海：剩余额度、重置时间和任务状态，全都知道。**

## 一眼看懂

| 你关心的 | CodexNotch 怎么展示 |
| --- | --- |
| **额度还剩多少** | 实体刘海有 5 小时窗口时，左侧用圆环或波浪球显示 5h，右侧显示周额度；展开卡片先列 5h，再列周额度。 |
| **什么时候重置** | 展开卡片直接显示精确重置时刻和秒级倒计时。 |
| **多次重置分别何时到期** | 点击“可重置 N 次”，一次展开全部重置额度的到期时间与剩余倒计时。 |
| **切到其他应用会不会消失** | 不会。浏览器、IDE 或其他应用在前台时，额度和状态仍在刘海旁。 |
| **任务有没有在跑** | 运行时显示蓝色状态回声；完成后切换为绿色对号。 |

## 核心体验

### 额度始终在眼前

左侧有 5 小时额度时显示额度，否则显示所选状态图标。即使没有任务正在运行，周额度也会保留在右侧。设置中选择“关闭”可隐藏左侧，展开卡片仍显示所有可用额度，并先列出 5 小时明细。切到浏览器、IDE 或其他应用，额度仍然可见。

### 不只显示百分比，还精确到重置秒数

悬停刘海即可展开卡片，查看：

- 本周额度和 5 小时额度明细与横向进度条（有对应窗口时显示）
- 当前重置时刻与秒级倒计时
- 所有可用重置额度的精确到期时间
- 当前活动任务与最近对话

额度窗口根据接口返回的 `limit_window_seconds` 动态识别。刘海和浮动横条模式下，周额度均显示在右侧；左侧有 5 小时额度时显示额度，选择“关闭”后隐藏。展开卡片先列出 5 小时额度明细。

### 切换应用，额度还在

CodexNotch 是独立的原生 macOS 应用，不依赖 Atoll、CodexIsland、CC Switch 或其他宿主程序。你可以离开 Codex 窗口，额度、重置时间和任务状态仍然可见。

### 任务状态也在同一个位置

Codex 运行时显示蓝色状态回声，以及两侧实际可见额度指标背后的克制光晕；完成后切换为绿色对号。展开卡片中的任务可以直接打开 `codex://threads/<thread-id>`，不用重新寻找刚才的对话。

## 立即安装

前往 [**GitHub Releases**](https://github.com/fengdwx/codex-notch/releases/latest)。如果该版本提供 `CodexNotch-...dmg`，优先下载 DMG；否则使用 ZIP：

1. DMG 直接打开磁盘映像；ZIP 则先解压。
2. 在 DMG 窗口中，将 `CodexNotch.app` 拖到“Applications”快捷方式上。（ZIP 需要手动将应用拖入“应用程序”。）
3. 登录 ChatGPT 并使用一次 Codex，然后启动 CodexNotch。

无需安装 Swift、Swift Package Manager 或 Xcode。

> 同时保留 ZIP 作为备选压缩包。当前公开包默认使用 ad-hoc 签名，DMG 不会消除 macOS 的首次运行提示；请在“系统设置 → 隐私与安全性”中选择“仍要打开”，或右键应用后选择“打开”。

CodexNotch 默认读取 `~/.codex`。如果你的 Codex 使用其他目录，可通过 `CODEX_HOME` 指定。

## 自定义你看到的信息

鼠标移入实体刘海并点击右下角“设置”，或通过刘海右键菜单、应用菜单打开设置：

- 在顺时针额度圆环与波浪球之间切换
- 选择浮动条中间样式，并设置最多 12 个字符的个人签名
- 选择中文或英文界面（默认英文）
- 设置展开卡片显示的最近对话数量（0–5，设置为 0 可隐藏最近对话）
- 检查最新正式版本，在应用内下载、安装并重启（0.2.1 起支持）
- 修改后立即生效，并保存在本机
- 在“通用”中启用登录时自动启动
- 关闭左侧显示，额度明细仍可在展开卡片查看
- 通过应用内开关控制动画，不与系统“减少动态效果”联动

无刘海屏幕（包括镜像屏幕）会在屏幕顶部居中显示浮动条。

<details>
<summary><strong>视觉与交互细节</strong></summary>

- 左右紧凑指标使用相同的 24pt 对齐容器，避免图标下沉或被摄像头区域遮挡。
- 额度环从 12 点方向开始，按顺时针表达进度；额度不低于 20% 时为绿色，低于 20% 时为红色，数据缺失时为灰色。
- 只有任务运行时，额度渐变或波浪才会运动；签名流光在空闲和完成时也持续运动。在应用内关闭动画后，两者都保持静止。
- 展开卡片只从紧凑岛体向下展开；收起后回收透明画布，避免拦截刘海外的鼠标操作。
- 数字始终显示在额度指标内部，不在旁边重复显示。

</details>

## 数据与隐私

- 认证令牌只从 `CODEX_HOME/auth.json` 读取并保存在进程内存，不写入 CodexNotch 缓存或日志。
- 额度与可用重置额度明细分别请求 ChatGPT 的只读 usage 和重置额度接口。
- 任务状态只解析本地 `CODEX_HOME/sessions` 中的 rollout JSONL 文件。
- 对话标题按 thread ID 优先匹配 `CODEX_HOME/session_index.jsonl` 中最新的简短 `thread_name`，再回退到只读 `CODEX_HOME/state_5.sqlite` 中的 `threads.title`；解析标题时不读取 rollout 消息正文、`first_user_message` 或 `preview`。
- 不记录 Authorization header、完整 usage 响应、用户消息正文或对话标题缓存。
- 手动检查更新读取 GitHub 公开更新列表，并下载经过签名的安装包；不发送 Codex 凭据、额度数据、任务数据或用户内容。

usage 接口属于 ChatGPT 内部接口，字段未来可能变化。接口异常时会保留最后一次成功额度，任务监听仍会继续工作。

<details>
<summary><strong>从源码构建</strong></summary>

从源码构建需要 Xcode 16 或更新版本，以及该 Xcode 版本支持的 macOS 系统。构建后的应用支持 macOS 14 或更高版本。CI 使用 macOS 14 和 Xcode 16.2：

```sh
swift test
./scripts/build_app.sh
open dist/CodexNotch.app
```

生成可发布的 ZIP 和 DMG：

```sh
./scripts/release.sh
```

脚本会运行测试、构建 release `.app`、校验代码签名，生成 ZIP、DMG 及各自的 SHA-256 文件，挂载 DMG 验证其中的应用，并使用发布者钥匙串为 ZIP 签名、生成更新列表。具体步骤见[更新发布流程](docs/updating.md)。DMG 改善安装流程，但不等同于 Developer ID 签名或苹果公证。只想跳过签名时可使用：

```sh
SIGN_IDENTITY=none ./scripts/build_app.sh
```

</details>

## 当前边界

CodexNotch 目前处于 0.x 版本阶段，不提供终止 Codex 任务、成本统计、云同步、远程通知、未经用户操作自动下载安装、宠物动画或 Mac App Store 分发。ChatGPT Classic 不属于监听目标。

## 开源许可

CodexNotch 使用 [MIT License](LICENSE)。如果它缓解了你的额度焦虑，欢迎点一个 Star。