[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81254":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":11,"openIssues":13,"contributorsCount":12,"subscribersCount":12,"size":12,"stars1d":12,"stars7d":12,"stars30d":12,"stars90d":12,"forks30d":12,"starsTrendScore":12,"compositeScore":12,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":14,"fork":14,"defaultBranch":15,"hasWiki":16,"hasPages":14,"topics":17,"createdAt":9,"pushedAt":9,"updatedAt":18,"readmeContent":19,"aiSummary":20,"trendingCount":12,"starSnapshotCount":12,"syncStatus":21,"lastSyncTime":22,"discoverSource":23},81254,"codex-ha-bridge","ofilis\u002Fcodex-ha-bridge","ofilis","Publishes OpenAI Codex usage limits to Home Assistant via MQTT, including 5-hour and weekly reset times.",null,"JavaScript",21,0,1,false,"main",true,[],"2026-06-12 02:04:12","# Codex Home Assistant MQTT Bridge\n\nPublish OpenAI Codex usage limits to Home Assistant over MQTT.\n\n**Codex Home Assistant MQTT Bridge** reads the same Codex usage information used by the Codex client, normalizes it, and publishes Home Assistant MQTT Discovery entities for the 5-hour and weekly usage windows.\n\nIt is designed to be lightweight: there are no npm package dependencies, and the included Windows helper scripts can run the bridge silently in the background at sign-in.\n\n---\n\n## Features\n\n- Publishes Codex usage to Home Assistant via MQTT.\n- Creates Home Assistant sensors automatically with MQTT Discovery.\n- Tracks 5-hour usage and remaining percentage.\n- Tracks weekly usage and remaining percentage.\n- Publishes reset times:\n  - `Codex 5h Reset`: `16:49`\n  - `Codex Weekly Reset`: `12\u002F05 - 09:01`\n- Publishes plan, credits, and limit status.\n- Runs without npm dependencies.\n- Includes Windows startup helpers that run silently in the background.\n\n---\n\n## Screenshots\n\nCodex usage shown on a small Home Assistant dashboard display:\n\n\u003Cimg src=\"docs\u002Fimages\u002Fpic-1.jpg\" alt=\"Codex usage shown on a small Home Assistant dashboard display\" width=\"720\">\n\nHome Assistant MQTT device and sensor entities:\n\n\u003Cimg src=\"docs\u002Fimages\u002Fpic-2.png\" alt=\"Codex usage sensors in Home Assistant\" width=\"640\">\n\n---\n\n## Home Assistant entities\n\nThe bridge publishes these sensors:\n\n| Sensor | Example |\n| --- | --- |\n| `Codex 5h Used` | `49%` |\n| `Codex 5h Remaining` | `51%` |\n| `Codex 5h Reset` | `16:49` |\n| `Codex Weekly Used` | `8%` |\n| `Codex Weekly Remaining` | `92%` |\n| `Codex Weekly Reset` | `12\u002F05 - 09:01` |\n| `Codex Credits` | `0 credits` |\n| `Codex Plan` | `plus` |\n| `Codex Limit Status` | `OK` |\n\n---\n\n## How it works\n\n1. The bridge reads Codex authentication data from your local Codex configuration directory, or from an optional access token fallback.\n2. It requests Codex usage information from the Codex backend usage endpoint.\n3. It flattens the response into simple values suitable for MQTT state payloads.\n4. It publishes MQTT Discovery configs so Home Assistant creates the sensors automatically.\n5. It periodically republishes the current usage state and availability.\n\nDefault MQTT topics:\n\n```text\nhomeassistant\u002Fsensor\u002Fcodex_usage\u002F...\ncodex\u002Fusage\u002Fstate\ncodex\u002Fusage\u002Favailability\n```\n\n---\n\n## Requirements\n\n- Windows, macOS, or Linux with Node.js 20 or newer.\n- Home Assistant with MQTT enabled.\n- A working MQTT broker, such as the Mosquitto add-on.\n- A valid Codex login on the machine running the bridge.\n\nThe Windows helper scripts can also use the Node.js runtime bundled with the Codex desktop app when it is available.\n\n---\n\n## Quick start on Windows\n\n1. Copy `.env.example` to `.env`.\n2. Edit `.env` with your MQTT settings.\n3. Double-click `start.bat` to test the bridge.\n4. Double-click `install-startup-task.bat` to run it silently when you sign in to Windows.\n\nExample `.env`:\n\n```env\nMQTT_URL=mqtt:\u002F\u002F192.168.1.50:1883\nMQTT_USERNAME=ha_demo_user\nMQTT_PASSWORD=your-password\nPOLL_SECONDS=60\n```\n\nDo not commit your `.env` file. It contains your MQTT password and may contain Codex-related credentials.\n\n---\n\n## Manual start\n\nIf Node.js is installed and available in your terminal:\n\n```powershell\nnode src\u002Findex.js\n```\n\nOr through npm:\n\n```powershell\nnpm start\n```\n\nIf you are using the Windows helper:\n\n```powershell\n.\\run.ps1\n```\n\n---\n\n## Silent startup on Windows\n\nTo create a Windows startup shortcut:\n\n```powershell\npowershell -NoProfile -ExecutionPolicy Bypass -File .\\install-startup-task.ps1\n```\n\nOr double-click:\n\n```text\ninstall-startup-task.bat\n```\n\nThis creates a shortcut in the user's Windows Startup folder and starts the bridge immediately. It does not keep a terminal window open.\n\nTo remove the startup shortcut:\n\n```powershell\npowershell -NoProfile -ExecutionPolicy Bypass -File .\\uninstall-startup-task.ps1\n```\n\nWhen installed as a silent Windows startup app, logs are written to:\n\n```text\nlogs\u002Fbridge.log\n```\n\n---\n\n## Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `MQTT_URL` | `mqtt:\u002F\u002Fhomeassistant.local:1883` | MQTT broker URL. The built-in MQTT client supports `mqtt:\u002F\u002F`. |\n| `MQTT_USERNAME` | empty | MQTT username. |\n| `MQTT_PASSWORD` | empty | MQTT password. |\n| `CODEX_HOME` | `~\u002F.codex` | Codex config\u002Fauth directory. |\n| `CODEX_ACCESS_TOKEN` | empty | Optional bearer token fallback. |\n| `CHATGPT_ACCOUNT_ID` | empty | Optional account ID override when needed by the Codex backend request. |\n| `CODEX_BACKEND_URL` | `https:\u002F\u002Fchatgpt.com\u002Fbackend-api\u002Fwham\u002Fusage` | Optional backend usage endpoint override. |\n| `CODEX_REFRESH_TOKEN_URL` | `https:\u002F\u002Fauth.openai.com\u002Foauth\u002Ftoken` | Optional token refresh endpoint override. |\n| `POLL_SECONDS` | `60` | How often to publish usage updates. |\n| `MQTT_BASE_TOPIC` | `codex\u002Fusage` | MQTT state\u002Favailability topic prefix. |\n| `HA_DISCOVERY_PREFIX` | `homeassistant` | Home Assistant MQTT discovery prefix. |\n| `DEVICE_ID` | `codex_usage` | Home Assistant device identifier. |\n| `DEVICE_NAME` | `Codex Usage` | Home Assistant device name. |\n\n---\n\n## Example Home Assistant dashboard cards\n\n5-hour usage gauge:\n\n```yaml\ntype: gauge\nentity: sensor.codex_5h_used\nname: Codex 5h\nmin: 0\nmax: 100\nseverity:\n  green: 0\n  yellow: 70\n  red: 90\n```\n\nWeekly usage gauge:\n\n```yaml\ntype: gauge\nentity: sensor.codex_weekly_used\nname: Codex Weekly\nmin: 0\nmax: 100\nseverity:\n  green: 0\n  yellow: 70\n  red: 90\n```\n\n---\n\n## Repository contents\n\n```text\n.\n├── .env.example\n├── README.md\n├── package.json\n├── start.bat\n├── run.ps1\n├── run-service.ps1\n├── run-hidden.vbs\n├── install-startup-task.bat\n├── install-startup-task.ps1\n├── uninstall-startup-task.ps1\n├── docs\u002F\n│   └── images\u002F\n└── src\u002F\n    ├── auth.js\n    ├── codexUsage.js\n    ├── config.js\n    ├── index.js\n    ├── mqttHa.js\n    └── simpleMqtt.js\n```\n\n### Main files\n\n- `src\u002Findex.js` — bridge entry point and polling loop.\n- `src\u002Fconfig.js` — environment\u002Fconfig loading.\n- `src\u002Fauth.js` — Codex authentication handling.\n- `src\u002FcodexUsage.js` — Codex usage request and normalization.\n- `src\u002FmqttHa.js` — Home Assistant MQTT Discovery and state publishing.\n- `src\u002FsimpleMqtt.js` — minimal MQTT client implementation.\n- `start.bat`, `run.ps1`, `run-service.ps1`, `run-hidden.vbs` — Windows run helpers.\n- `install-startup-task.ps1` \u002F `uninstall-startup-task.ps1` — Windows startup shortcut management.\n\n---\n\n## Development \u002F validation\n\nThis project has no npm dependencies. To validate JavaScript syntax:\n\n```powershell\nnpm run check\n```\n\nThe check script runs `node --check` against the source files.\n\n---\n\n## Troubleshooting\n\n### Sensors do not appear in Home Assistant\n\n- Confirm MQTT is enabled in Home Assistant.\n- Confirm your MQTT broker URL, username, and password in `.env`.\n- Check that Home Assistant MQTT Discovery is enabled.\n- Check the bridge logs for MQTT connection errors.\n\n### Usage values are not updating\n\n- Confirm Codex is logged in on the same machine running the bridge.\n- Confirm `CODEX_HOME` points to the correct Codex config\u002Fauth directory if you use a non-default location.\n- Run the bridge manually with `node src\u002Findex.js` to see foreground logs.\n\n### The Windows startup task does not run silently\n\n- Re-run `install-startup-task.bat` or `install-startup-task.ps1`.\n- Check `logs\u002Fbridge.log` in the repository directory.\n- Confirm Node.js is available, or that the Codex desktop app bundled Node.js runtime can be found by the helper scripts.\n\n---\n\n## Security and privacy\n\n- Do not commit `.env`.\n- Do not share `CODEX_ACCESS_TOKEN` if you use it.\n- The bridge does not publish your Codex token or MQTT password to Home Assistant.\n- MQTT state payloads contain usage\u002Flimit information only.\n- If OpenAI changes the Codex backend endpoint or response shape, the bridge may need an update.\n\n---\n\n## Notes and limitations\n\nThis project uses the Codex backend usage endpoint used by Codex itself. It is not a separately documented public API.\n\nBecause of that, endpoint paths, authentication behavior, or response formats may change without notice. If that happens, update the bridge before relying on it for automations or monitoring.\n","Codex Home Assistant MQTT Bridge 项目通过MQTT协议将OpenAI Codex的使用限制发布到Home Assistant中，包括5小时和每周的重置时间。该项目的核心功能是自动创建Home Assistant传感器以显示Codex在不同时间段内的使用情况与剩余百分比，并且能够报告具体的重置时间、计划类型、信用额度及限额状态。它设计得非常轻量级，不依赖任何npm包，易于在Windows、macOS或Linux上运行，特别适合需要监控和管理Codex API调用配额的家庭自动化场景。此外，项目提供了适用于Windows环境下的启动助手脚本，可实现后台静默运行。",2,"2026-06-11 04:04:03","CREATED_QUERY"]