Home-Assistant Codex Usage is a native Home Assistant custom integration that displays Codex subscription usage as sensor entities. It talks directly to the service, so no MQTT broker, Node.js process, bridge, or add-on is required.
The usage-response handling was originally informed by ofilis/codex-ha-bridge.
Warning
This integration uses undocumented endpoints used by official Codex clients. They are not part of OpenAI's public API and may change or stop working without notice.
- Home Assistant 2026.8 or newer
- A Codex-enabled OpenAI account or workspace that permits device-code login
- Internet access from Home Assistant to
chatgpt.comandauth.openai.com
- Open HACS in Home Assistant.
- Add
https://github.com/Xlinx64/Home-Assistant-Codex-Usageas a custom repository of type Integration. - Install Home-Assistant Codex Usage and restart Home Assistant.
- Open Settings → Devices & services → Add integration → Home-Assistant Codex Usage.
Copy custom_components/codex_usage to:
/config/custom_components/codex_usage
Restart Home Assistant, then open:
Settings → Devices & services → Add integration → Home-Assistant Codex Usage
Home Assistant displays a one-time code and an OpenAI verification link. Open the link, sign in, enter the code, then return to Home Assistant and submit the form. Home Assistant receives its own Codex session.
Device-code login must be allowed for the selected account or workspace.
| Entity | Description |
|---|---|
| 5-hour usage | Used percentage in the short usage window |
| 5-hour remaining | Remaining percentage in the short usage window |
| 5-hour reset | Timestamp at which the short usage window resets |
| Weekly usage | Used percentage in the weekly usage window |
| Weekly remaining | Remaining percentage in the weekly usage window |
| Weekly reset | Timestamp at which the weekly usage window resets |
| Credits | Current credits balance |
| Plan | Codex subscription plan reported by the service |
| Limit status | Current rate-limit status |
All entities share one cloud request per update. The default interval is 60 seconds and can be changed in the integration options, with a minimum of 30 seconds.
The integration communicates directly with auth.openai.com and
chatgpt.com; it does not use a maintainer-operated relay or send telemetry to
the maintainer.
Home Assistant stores the issued access token, refresh token, and Codex account
identifier in the integration's config entry. These credentials are sensitive,
are not separately encrypted by this integration, and may be included in Home
Assistant backups. Protect the Home Assistant host, its .storage directory,
and all backups. Never post .storage files, tokens, authorization codes,
account identifiers, complete HTTP headers, or unredacted logs in an issue.
Because the device authorization flow is undocumented, this project cannot guarantee that the issued session is limited to reading usage data. The exposed usage, plan, and credit sensor states may also be retained by Home Assistant's recorder according to the user's recorder configuration.
The account or organization may have disabled device-code login. Ask the workspace administrator whether device authorization is permitted. The integration intentionally does not reuse another application's credentials.
Complete the browser login and enter the displayed one-time code before submitting the Home Assistant form again. If the code expired, restart setup to request a new one.
Check Home Assistant logs for custom_components.codex_usage. Temporary cloud
errors recover on a later polling cycle. If Home Assistant requests
reauthentication, reconnect the integration to issue a new independent session.
- Open Settings → Devices & services → Home-Assistant Codex Usage and delete the config entry.
- If installed with HACS, uninstall Home-Assistant Codex Usage there. For
a manual installation, delete
/config/custom_components/codex_usage. - Restart Home Assistant.
Deleting the config entry removes Home Assistant's local copy of the Codex credentials. The integration does not have a documented server-side revocation endpoint and therefore cannot guarantee that deleting the entry immediately invalidates the session at OpenAI.
Bug reports and contributions are welcome. See CONTRIBUTING.md for the development setup and required checks.
This project is developed with assistance from AI coding tools, including OpenAI Codex. AI-assisted changes are reviewed by the maintainer and must pass the same tests, linting, and security checks as manually written changes. The maintainer remains responsible for design, correctness, licensing, and releases.
MIT. See LICENSE.
This community project is not affiliated with or endorsed by OpenAI. Codex, ChatGPT, OpenAI, and their associated artwork and trademarks belong to their respective owners.