CodexView

CodexView 是面向 macOS 14+ Apple Silicon 的原生菜单栏应用。它从本机已登录的 codex app-server 读取主额度、周额度和重置时间，并可在 Codex 窗口标题栏的安全区域显示简洁 Overlay。

应用不修改或注入 Codex Desktop，不读取浏览器 Cookie，不访问私有网页接口，也不包含遥测或云同步。

CodexView 是非官方第三方项目，与 OpenAI 不存在隶属、赞助或背书关系。Codex 和 OpenAI 是其各自所有者的商标。

项目状态

当前版本为 0.1.0 预发布基线。源码和本机 ad-hoc 构建流程可用，但 Developer ID 签名、公证、DMG 以及完整的多显示器、Space、全屏、权限撤销和长期稳定性矩阵尚未完成。请不要把当前本机构建描述为经过公证的正式发行版。

一键运行

本机需要已经安装 Codex Desktop，以及 Xcode Command Line Tools 或 Xcode。首次准备工具链可在终端运行：

xcode-select --install

之后在 Finder 中双击根目录的：

运行 CodexView.command

脚本会自动完成 Release 构建、生成并临时签名 dist/CodexView.app，随后启动应用。应用是菜单栏程序，不显示 Dock 图标；启动后在屏幕右上角寻找 CV -- 或 CV 75%。

也可以从终端运行：

./scripts/run.sh

若要长期使用或开启“登录时启动”，请把生成的 dist/CodexView.app 拖入 /Applications，再从应用程序目录打开一次。

使用

• 菜单栏始终可用，显示连接状态、主/周额度、更新时间和 stale 状态。
• “立即刷新”会唤醒或重连本机 App Server。
• 标题栏 Overlay 默认开启，但只有在你主动允许“辅助功能”权限后才显示。
• Overlay 在 Codex 不处于前台、窗口最小化、全屏布局不安全、数据过期或标题栏空间不足时自动隐藏。
• “外观”支持跟随系统、浅色和深色；设置保存在本机 UserDefaults。
• “打开日志目录”仅打开本机诊断目录；结构化运行事件写入 macOS Unified Logging，不上传到任何远端。

辅助功能权限只读取 bundle identifier 为 com.openai.codex 的进程窗口位置、大小、最小化和全屏状态。额度读取与此权限无关，拒绝权限不会影响菜单栏。

开发与检查

swift build
./scripts/check.sh
./scripts/build-app.sh

本机 Command Line Tools 若存在编译器与默认 SDK 小版本不匹配，项目脚本会自动回退到已安装的兼容 SDK。也可显式指定：

CODEXVIEW_SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX15.4.sdk ./scripts/check.sh

check.sh 始终构建应用并运行不依赖测试框架的 CodexViewChecks。选择完整 Xcode 时还运行 Swift Testing 测试，包括 JSONL 拆包、协议兼容、stale/退避、布局坐标和假 App Server 集成测试。

工程结构

• Sources/CodexViewCore：模型、设置、可执行发现、JSONL、协议解析和 App Server actor 会话；不依赖 AppKit。
• Sources/CodexViewApp：应用生命周期、菜单栏、ServiceManagement、Accessibility、窗口跟踪和 NSPanel。
• Checks/CodexViewChecks：Command Line Tools 环境也能执行的核心回归检查。
• tests：Swift Testing 测试与脱敏协议 fixtures。
• scripts/build-app.sh：生成本机可运行的 .app。
• scripts/run.sh：构建并启动。

许可证

CodexView 采用 MIT License 开源。项目名称及 OpenAI/Codex 相关商标不因软件许可证而获得额外授权。

Git 管理

项目已初始化为 main 分支，构建目录、.app 产物、日志和本地环境文件均由 .gitignore 排除。常用流程：

git status
git diff
git add <文件>
git commit -m "说明本次改动"

请勿提交 dist/、.build/、个人日志、令牌、账号响应或未脱敏协议样本。

当前边界

本仓库提供可直接本机运行的 ad-hoc 签名 .app。面向他人分发所需的 Developer ID、Hardened Runtime、公证和 DMG 仍需要开发者证书，并属于预发布阶段；自动化通过也不能代替多显示器、Space、全屏、权限撤销和 8 小时稳定性人工验收。