AI Usage

ai-usage 是一個用 Node.js 寫的命令列工具，會顯示 Codex 和 Antigravity 的方案用量、重置時間，以及 Codex Reset Rate Limit 額度。Codex 視窗會依 API 實際回傳的長度判斷；若目前只回傳每週視窗，就只顯示 7 天用量。

需要什麼

• Windows、macOS 或 Linux
• Node.js 18 以上
• 不需要安裝第三方 npm 套件

使用

已發布到 npm 時，直接用 npx 執行：

npx @hochun836/ai-usage
npx @hochun836/ai-usage --provider codex
npx @hochun836/ai-usage --provider antigravity
npx @hochun836/ai-usage --json

如果是在本機 clone 的專案目錄中：

node src/index.js

--provider 可以指定 codex、antigravity 或 all。不指定時會查詢兩個 provider。

警示顏色

畫面會分開判斷兩件事：

• 剩餘用量低於門檻時，剩餘比例和進度條變紅
• 視窗剩餘時間低於門檻時，重置倒數和到期時間變紅

兩個門檻預設都是 15%，可以分開調整：

npx @hochun836/ai-usage --usage-warning-threshold 20 --time-warning-threshold 10

其他常用選項：

npx @hochun836/ai-usage --no-color
npx @hochun836/ai-usage --verbose
npx @hochun836/ai-usage --json

--verbose 會顯示 Antigravity 回傳的原始 quota 說明。--json 適合提供給其他程式處理，欄位名稱維持英文。

同步 Codex deadline 到 Google Calendar

src/sync-codex-to-gcal.js 會直接執行本專案的 src/index.js，取得 Codex 的用量重置與 Reset Credit deadline，再寫入使用者自己的 Google Calendar。此腳本使用 Google Calendar REST API，不需要其他第三方 npm 套件。

第一次設定

1. 在 Google Cloud 專案中啟用 Google Calendar API。
2. 建立 OAuth Desktop app credentials，下載 credentials JSON 檔案。請勿將此檔案提交到 Git。可參考 Google Calendar Node.js OAuth quickstart。
3. 將檔案放在預設位置：Windows 為 %LOCALAPPDATA%\ai-usage\credentials.json，macOS/Linux 為 ~/.config/ai-usage/credentials.json；也可以使用 --credentials 指定其他位置。
4. 第一次執行同步腳本時，腳本會在終端機顯示 Google OAuth 網址。請手動將網址貼到瀏覽器，登入 Google 帳號並授權；授權期間請保持同步腳本執行中，以接收瀏覽器回呼。
5. 授權 token 預設會儲存在 Windows 的 %LOCALAPPDATA%\ai-usage\google-calendar-token.json，或 macOS/Linux 的 ~/.config/ai-usage/google-calendar-token.json，後續執行會重用該 token。

credentials JSON 是 OAuth Desktop app 的應用程式設定，不是 Google 登入密碼；第一次執行不需要預先準備 token。

使用方式

先執行 dry-run 確認將要同步的 deadline：

node src/sync-codex-to-gcal.js --dry-run

正式同步到主要 Calendar：

node src/sync-codex-to-gcal.js --calendar-id primary

若要依 Calendar 名稱尋找目標，可以使用：

node src/sync-codex-to-gcal.js --calendar-name "我的日曆"

未指定 --calendar-id 時，預設尋找名稱為 我的日曆 的 Calendar。--token-file 與 --duration-minutes 都不是必要參數，前者有預設儲存位置，後者預設為 15 分鐘。同步時只會管理標題以 [Codex Deadline] 開頭的事件；如果本次沒有取得有效 deadline，會保留既有事件，不會刪除或新增任何內容。

常用選項：

node src/sync-codex-to-gcal.js --reminder 2d --reminder "1d popup"
node src/sync-codex-to-gcal.js --no-reminders
node src/sync-codex-to-gcal.js --duration-minutes 30

--credentials 也可以使用 GOOGLE_CALENDAR_CREDENTIALS 環境變數指定；token 儲存位置可以使用 --token-file 或 GOOGLE_CALENDAR_TOKEN_FILE 指定。這些檔案可能包含敏感資訊，請勿提交到 Git。

Codex 登入資料

工具會從使用者的 Codex 設定目錄讀取 auth.json：

• Windows：%USERPROFILE%\.codex\auth.json
• macOS/Linux：~/.codex/auth.json
• 設定 CODEX_HOME 後，會改用該目錄下的 auth.json

工具只在記憶體中使用 access token，不會把 token 印到畫面或寫入檔案。

Antigravity

查詢前請先啟動 Antigravity app 或 agy。工具會找出相關 process，取得它正在監聽的本機 port，再呼叫 language server 的 quota endpoint。

不同平台使用不同的系統指令：

• Windows 使用 PowerShell、Win32_Process 和 Get-NetTCPConnection
• macOS/Linux 使用 ps 和 lsof
• Linux 找不到 lsof 時，會再嘗試 ss

Antigravity 的 language server 是內部 API，版本更新後可能改變回應內容。某些 IDE 版本只提供 5 小時或 model-level quota，未必有完整的 7 天資料。

開發與測試

npm test
npm pack --dry-run

測試 parser 時可以使用 fixture，不需要連線：

node src/index.js --provider codex --codex-auth sample-auth.json --codex-usage-fixture usage.json --credits-fixture credits.json
node src/index.js --provider antigravity --antigravity-fixture sample.json

發布

npm login
npm test
npm publish

發布後，使用者可以執行 npx @hochun836/ai-usage。套件安裝後提供的命令仍然是 ai-usage。

參考

provider 的資料來源和探測方式參考 CodexBar 的 Codex 文件 與 Antigravity 文件。

License

MIT License，詳見 LICENSE。