Add native macOS quota widget

Author: makerjackie

CodexHelper.xcodeproj/project.pbxproj

@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1430"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      runPostActionsOnFailure = "NO">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "6D0C8BB10656508755A8F7E5"
+               BuildableName = "CodexHelper.app"
+               BlueprintName = "CodexHelper"
+               ReferencedContainer = "container:CodexHelper.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "F6F197AAF7B62CC6FB92971A"
+               BuildableName = "CodexHelperWidget.appex"
+               BlueprintName = "CodexHelperWidget"
+               ReferencedContainer = "container:CodexHelper.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      onlyGenerateCoverageForSpecifiedTargets = "NO">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "6D0C8BB10656508755A8F7E5"
+            BuildableName = "CodexHelper.app"
+            BlueprintName = "CodexHelper"
+            ReferencedContainer = "container:CodexHelper.xcodeproj">
+         </BuildableReference>
+      </MacroExpansion>
+      <Testables>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "6D0C8BB10656508755A8F7E5"
+            BuildableName = "CodexHelper.app"
+            BlueprintName = "CodexHelper"
+            ReferencedContainer = "container:CodexHelper.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+      <CommandLineArguments>
+      </CommandLineArguments>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "6D0C8BB10656508755A8F7E5"
+            BuildableName = "CodexHelper.app"
+            BlueprintName = "CodexHelper"
+            ReferencedContainer = "container:CodexHelper.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

CodexHelper.xcodeproj/project.xcworkspace/contents.xcworkspacedata

@@ -2,9 +2,9 @@
 
 ## One-line description
 
-**EN:** An open-source macOS menu bar companion for Codex. Safely continue capacity-interrupted tasks, see account limits, and keep up with official updates and docs.
+**EN:** An open-source macOS companion for Codex. See quota in a native widget or floating rail, and safely continue capacity-interrupted tasks.
 
-**中文：** 一个开源的 Codex macOS 菜单栏辅助工具：模型暂时满载时安全续跑原任务，随手查看额度、官方动态与文档。
+**中文：** 一个开源的 Codex macOS 辅助工具：用原生小组件或悬浮轨道查看额度，并在模型满载时安全续跑原任务。
 
 ## GitHub description
 
@@ -25,7 +25,7 @@ So I built **Codex Helper**. Auto Retry watches for that exact failure, waits wi
 - No project-file access
 - English + 中文
 - Built-in end-to-end test
-- Always-visible Codex quota + full dashboard
+- Native macOS widget + optional floating rail
 - Official Codex updates + docs
 - Signed in-app updates
 - MIT licensed
@@ -43,7 +43,7 @@ Codex 又因为“所选模型已满载”停住了，于是我做了 **Codex He
 - 不读取项目文件
 - 中英文支持
 - 内置端到端验证
-- 菜单栏常驻额度 + 完整主页面
+- 原生 macOS 小组件 + 可选悬浮轨道
 - Codex 官方动态与文档入口
 - 签名校验的应用内更新
 - MIT 开源
@@ -58,7 +58,7 @@ Temporary model capacity should be a pause, not the end of an agent task.
 
 **Codex Helper** is a native macOS menu bar companion. Auto Retry handles one frustrating edge case: `Selected model is at capacity. Please try a different model.` It tails the local Codex log, identifies the affected visible task, and schedules up to six retries with progressive backoff. Before every retry it checks the task session for newer user or turn activity, so it backs off if you already handled the problem yourself.
 
-When safe, it opens the original Codex task, submits a localized continuation message, and restores the app you were using. There is no cloud backend, telemetry, project-file access, or Codex binary modification.
+When safe, it opens the original Codex task, submits a localized continuation message, and restores the app you were using. A native macOS widget, menu bar item, and optional floating rail keep remaining quota visible. There is no cloud backend, telemetry, project-file access, or Codex binary modification.
 
 The project is deliberately small, auditable, bilingual, and MIT licensed.
 
@@ -68,6 +68,6 @@ The project is deliberately small, auditable, bilingual, and MIT licensed.
 
 **Codex Helper** 会处理这个烦人的边界情况：`Selected model is at capacity. Please try a different model.`。它会监听本地 Codex 日志，定位受影响的可见主任务，并按渐进退避最多安排 6 次重试。每次真正重试之前，它都会检查任务是否已经出现新的用户消息或新回合；如果你已经手动处理，它会自动让路。
 
-确认安全后，它会打开原 Codex 任务，提交本地化续跑消息，再恢复你此前使用的 App。菜单栏还能显示 Codex 额度窗口与重置时间、聚合官方动态和文档，并通过签名校验的应用内更新保持最新版。整个过程没有云端后端、没有遥测、不读取项目文件，也不修改 Codex 二进制。
+确认安全后，它会打开原 Codex 任务，提交本地化续跑消息，再恢复你此前使用的 App。原生 macOS 小组件、菜单栏和可选悬浮轨道都能显示剩余额度与重置时间。整个过程没有云端后端、没有遥测、不读取项目文件，也不修改 Codex 二进制。
 
 项目刻意保持小巧、可审计、中英双语，并采用 MIT 协议开源。

CodexHelper.xcodeproj/xcshareddata/xcschemes/CodexHelper.xcscheme

@@ -0,0 +1,45 @@
+# Codex Helper
+
+[简体中文](README.md) · [How it works](docs/how-it-works.md) · [MIT License](LICENSE)
+
+<p align="center">
+  <img src="assets/app-icon-source.png" width="150" alt="Codex Helper icon">
+</p>
+
+An open-source macOS companion for Codex. See remaining quota at a glance and safely continue the original task after a model-capacity interruption.
+
+> Not an official OpenAI project.
+
+## Features
+
+- Native macOS widget, menu bar quota, and an optional floating Status Rail
+- Remaining quota, reset countdowns, and color-coded quota levels
+- Guarded Auto Retry for the affected Codex task
+- English and Chinese UI, signed updates, official Codex news and docs
+
+<p align="center">
+  <img src="assets/status-rail-v0.6.0.webp" width="520" alt="Codex Helper floating Status Rail">
+</p>
+
+## Install
+
+Download the signed and Apple-notarized DMG from [GitHub Releases](https://github.com/makerjackie/codex-helper/releases), then drag it to Applications. Requires macOS 13+ and the Codex desktop app.
+
+Native widget: Control-click the desktop → **Edit Widgets** → search for **Codex Helper**.
+
+Quota and widgets do not need Accessibility permission. Permission is needed only when Auto Retry submits a continuation in Codex. Codex Helper never prompts for it automatically at launch or during its own tests.
+
+## Development
+
+```bash
+git clone https://github.com/makerjackie/codex-helper.git
+cd codex-helper
+./test.sh
+./install.sh
+```
+
+See [How it works](docs/how-it-works.md) for retry safeguards and privacy boundaries.
+
+## License
+
+[MIT](LICENSE)

MARKETING.md

@@ -1,103 +1,44 @@
 # Codex Helper
 
-[简体中文](README.zh-CN.md) · [How it works](docs/how-it-works.md) · [Releasing](docs/releasing.md) · [MIT License](LICENSE)
+[English](README.en.md) · [工作原理](docs/how-it-works.zh-CN.md) · [MIT License](LICENSE)
 
 <p align="center">
-  <img src="assets/app-icon-source.png" width="180" alt="Codex Helper icon">
+  <img src="assets/app-icon-source.png" width="150" alt="Codex Helper 图标">
 </p>
 
-An unofficial, open-source macOS companion for Codex: a quiet horizontal Status Rail for remaining quota, guarded Auto Retry, official updates and documentation, and signed in-app updates.
+一个开源的 macOS Codex 辅助工具。直接查看剩余额度，并在模型满载时安全续跑原任务。
 
-> Not affiliated with or endorsed by OpenAI.
+> 非 OpenAI 官方项目。
 
-## Download
+## 功能
 
-Download the signed and Apple-notarized DMG from [GitHub Releases](https://github.com/makerjackie/codex-helper/releases), drag **Codex Helper** into Applications, and open it once.
-
-Requirements: macOS 13+ and the Codex desktop app.
-
-On first launch, allow **Codex Helper** in **System Settings → Privacy & Security → Accessibility**. Codex Helper needs its own permission because it is a separate app that focuses the Codex composer and submits the continuation message. If you used the earlier Codex Auto Retry prototype, this rename changes the app name, executable, bundle ID, and signing identity, so macOS treats Codex Helper as a new app and asks once more. Developer ID-signed updates with the same identity should not normally require permission again.
-
-## Menu bar and dashboard
-
-Click the Codex Helper menu bar icon to:
-
-- turn Auto Retry on or off;
-- see the primary Codex remaining quota percentage directly beside the menu bar icon;
-- show or hide an always-on-top Codex Status Rail with reset countdowns;
-- see every quota window, reset time, and reset-credit count in the first-level menu;
-- choose Automatic, English, or Simplified Chinese;
-- enable or disable Launch at Login;
-- automatically check and download signed Codex Helper updates;
-- run a safe end-to-end Auto Retry test against a task you choose;
-- read the latest official Codex changelog and Codex-related OpenAI news;
-- open Codex documentation, troubleshooting, commands, and Tibo's X profile;
-- open the dashboard, Accessibility Settings, or logs;
-- quit Codex Helper completely.
-
-You can also search for **Codex Helper** in Spotlight. Opening it again brings up the redesigned dashboard, led by one spacious quota overview and a flat two-column control area instead of a stack of settings cards. Auto Retry, updates, news, documentation, and preferences remain available on one page.
-
-<p align="center">
-  <img src="assets/status-rail-v0.6.0.webp" width="520" alt="Codex Helper horizontal Status Rail">
-</p>
+- 原生 macOS 小组件、菜单栏额度和可选悬浮状态轨道
+- 显示剩余额度、重置倒计时与额度颜色提醒
+- 模型满载后自动定位并重试原 Codex 任务
+- 中英文、自动更新、Codex 官方动态与文档入口
 
 <p align="center">
-  <img src="assets/dashboard-v0.6.0.webp" width="760" alt="Codex Helper dashboard">
+  <img src="assets/status-rail-v0.6.0.webp" width="520" alt="Codex Helper 悬浮状态轨道">
 </p>
 
-## Auto Retry
-
-When Codex reports:
-
-```text
-Selected model is at capacity. Please try a different model.
-```
-
-Codex Helper:
-
-1. Watches `~/.codex/log/codex-tui.log` and extracts the affected task ID.
-2. Handles only visible root tasks and ignores hidden subagents.
-3. Retries after `8 / 20 / 45 / 90 / 180 / 300` seconds, up to six times.
-4. Cancels if you already sent a message or a new turn started.
-5. Opens the original Codex task, submits a localized continuation prompt inside Codex, and restores the app you were using.
+## 安装
 
-It does not modify Codex, proxy network traffic, read project files, or store conversation content. It retries the same task; it does not automatically switch models.
+从 [GitHub Releases](https://github.com/makerjackie/codex-helper/releases) 下载已经签名和 Apple 公证的 DMG，拖入“应用程序”即可。要求 macOS 13+ 和 Codex 桌面版。
 
-## Usage
+原生小组件：在桌面空白处右键 → **编辑小组件** → 搜索 **Codex Helper**。
 
-The menu bar percentage, dashboard, and Status Rail read `account/rateLimits/read` from the official local Codex App Server. The API reports `usedPercent`; Codex Helper displays the remaining quota as `100 - usedPercent`, matching the direction used by Codex itself. The interface stays neutral while the circular gauge and small status accents change from teal at 50–100%, to amber at 10–50%, to pink-red below 10%. The Status Rail also shows reset countdowns, reset credits, refresh, dashboard, and hide controls. Codex Helper uses the authentication already managed by Codex and never reads tokens directly from `~/.codex/auth.json`.
+额度和小组件不需要辅助功能权限。只有开启“自动重试”并让 App 代为提交续跑消息时才需要授权；Codex Helper 不会在启动或测试时自动弹出授权请求。
 
-## Automatic updates
-
-Automatic updates are enabled by default. Codex Helper checks the latest GitHub Release at most once per day and downloads a newer DMG in the background. Installation remains a visible **Install and Restart** action so an update never interrupts work unexpectedly.
-
-Before replacement, Codex Helper verifies the published SHA-256 checksum, Developer ID bundle identifier and Team ID, and Gatekeeper acceptance. If the app location is not writable, it leaves the current version untouched and reports that automatic installation is unavailable.
-
-## Verify Auto Retry without waiting for an outage
-
-Choose **Test Auto Retry…** from the menu bar, select an idle recent Codex task with no draft in its composer, and confirm. Codex Helper creates a synthetic capacity event containing that task ID, runs it through the production matcher and visible-task check, waits three seconds, checks for newer activity, then opens the task and submits one clearly marked test message. A reply containing **Codex Helper test passed** verifies the complete routing and GUI-control chain on your installed Codex version.
-
-During a real failure, the Codex log line contains `thread_id=<UUID>` beside the exact capacity error. Codex Helper verifies that UUID against `~/.codex/session_index.jsonl`, waits with backoff, re-checks the task for newer activity, then opens `codex://threads/<UUID>`. It submits only when Accessibility reports that Codex is frontmost and the focused composer is an empty text area; it also checks the target session afterward for the submitted prompt.
-
-## What’s New and Learn Codex
-
-The menu reads the public [Codex changelog RSS](https://learn.chatgpt.com/docs/changelog/rss.xml) and [OpenAI News RSS](https://openai.com/news/rss.xml), keeping only Codex-related OpenAI News items. Results are cached locally; successful feeds refresh every six hours, while failures back off for at least 15 minutes. The Tibo entry is a normal browser link; Codex Helper does not scrape X.
-
-## Build from source
+## 开发
 
 ```bash
 git clone https://github.com/makerjackie/codex-helper.git
 cd codex-helper
+./test.sh
 ./install.sh
 ```
 
-Source builds use local ad-hoc signing and can require Accessibility permission again after rebuilding. For normal use, prefer the Developer ID-signed Release build.
-
-## Test
-
-```bash
-./test.sh
-```
+更详细的识别、重试和隐私边界见[工作原理](docs/how-it-works.zh-CN.md)。
 
 ## License