Installation

Installation

This page is the user-facing install walkthrough. For the shortest version, use the repository README.

Requirements

• Home Assistant 2026.5.0 or newer.
• HACS installed.
• A ChatGPT account or plan with Codex access.
• A basic understanding of Home Assistant Assist exposed entities.

Install through HACS

1. Open HACS in Home Assistant.

2. Open the three-dot menu.

3. Choose Custom repositories.

4. Add this repository URL:

   https://github.com/itsreverence/ha-codex-assist
   

5. Set the category to Integration.

6. Install Codex Assist.

7. Restart Home Assistant.

Add the integration

1. Go to Settings → Devices & services.
2. Select Add integration.
3. Search for Codex Assist.
4. Follow the device-code sign-in flow.
5. When prompted, sign in with the ChatGPT/Codex account you want Home Assistant to use.

Do not paste tokens, cookies, or browser session values into Home Assistant. The integration should guide you through device-code sign-in.

Select Codex Assist in Assist

After setup:

1. Open Home Assistant Assist pipeline settings.

2. Choose Codex Assist as the conversation agent for the pipeline you want to test.

3. Start with a harmless prompt, such as:

   What devices are exposed to you?
   

4. If you want to test control, use a low-impact exposed light first.

After updates

HACS custom integrations usually need a Home Assistant restart after installation or update. If conversation.codex_assist does not appear after an update, restart first, then check logs.