Skip to content

About

Unofficial Home Assistant Assist agent using ChatGPT/Codex subscription access

Topics

Resources

Contributing

Security policy

Stars

26 stars

Watchers

1 watching

Forks

Latest commit

 

History

153 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Codex Assist for Home Assistant

Codex Assist icon

Latest release CI Available in the Marketplace and HACS

Use OpenAI Codex / ChatGPT as a Home Assistant Assist conversation agent and AI Task provider.

Codex Assist signs in with Codex-style ChatGPT device-code auth. By default it keeps device control inside Home Assistant's normal exposed-entity safety model, and it does not require an OpenAI API key.

Experimental: this project is not affiliated with OpenAI or Home Assistant. Codex backend compatibility may change with upstream Codex updates.

Quick start

You need Home Assistant 2026.6.0 or newer and a ChatGPT account or plan with Codex access. Home Assistant 2026.11 and newer install it from the built-in Marketplace. Older versions need HACS.

Open in the Marketplace Open HACS Add the Codex Assist integration

1. Install

Codex Assist is in the default catalog, so you do not add a custom repository.

On Home Assistant 2026.11 or newer:

  1. Go to Settings → Marketplace, or use the Marketplace button above.
  2. Search for Codex Assist, open it, and select Install. Confirm the version, then select Install again.

On Home Assistant 2026.10 or older:

  1. In the Home Assistant sidebar, open HACS, or use the HACS button above.
  2. Search for Codex Assist, open it, and select Download.
  3. Restart Home Assistant.

If it does not appear after a new release or a catalog change, try again later. Updates through either one need a Home Assistant restart.

2. Sign in

Sign-in uses a device code, so you approve it in a browser. The browser can be on any device.

  1. Go to Settings → Devices & services → Add integration, or use the button above. Search for Codex Assist and select it.
  2. Select Submit. Home Assistant shows a web address and a short code.
  3. Open that address in a browser, sign in to ChatGPT, and enter the code within 15 minutes.
  4. Return to Home Assistant and select Submit. If it says the code has not been approved yet, wait a few seconds and select Submit again. If the code has expired, select Submit for a new one.
  5. Choose a chat model from the list, then select Submit. Setup creates a conversation agent named Codex Assist and an AI Task entity named Codex Assist AI Task.

If sign-in does not start or the code page reports an error, device-code login may be turned off for your account. OpenAI's authentication guide says a personal account enables it in ChatGPT security settings, and a workspace admin controls it for a workspace. Home Assistant stores the sign-in itself. Do not paste tokens or copy them from Codex CLI or another tool.

Codex Assist supports one sign-in. To change accounts or sign in again, use Reconfigure on the existing entry.

3. Choose Codex Assist in your pipeline

  1. Go to Settings → Voice assistants.
  2. Open an existing assistant, or select Add assistant.
  3. Set Conversation agent to Codex Assist.

4. Try a safe first request

Expose one harmless entity to Assist before you ask anything. A single light or a read-only sensor is a good choice. Open Settings → Voice assistants and use the Expose tab. Safe Entity Exposure has the steps and the entities to keep unexposed.

Then ask Assist about it by its own name. For example, if you exposed a light named Desk lamp:

Is the desk lamp on?

Example Assist chat in which Codex Assist reports that yard lights are on and turns them off

If something fails, start with Troubleshooting.

What it does

Assist conversations. Codex Assist registers as a normal Assist conversation agent and streams replies. One sign-in can serve several agents, each with its own name, prompt, and model. By default it reads and controls only the entities you expose to Assist, through Home Assistant's own Assist LLM API.

Home Assistant tools. Each conversation agent chooses which of Home Assistant's LLM APIs it may use, under Advanced chat settings → Home Assistant tools. Device control (Assist) is the default. On Home Assistant 2026.11 and newer you can also choose Home Assistant, an admin-only API for diagnostics and management that can run any action, and every MCP server you connect through Home Assistant's MCP integration adds its own choice. Give extra tools to a separate agent rather than your everyday voice agent. Home Assistant refuses admin-only APIs when no admin user made the request, which is the case for most voice satellites. Clear every choice for a chat-only agent.

AI Task. It generates plain text or structured data, reads supported image attachments (up to four images, 10 MiB each, 20 MiB total), and generates images. See the AI Task example.

Hosted web search. Off by default. When on, the model can search for current information. The model is asked to keep raw URLs out of spoken replies, which is not guaranteed.

Agents and settings. Each conversation agent and the AI Task entity keep their own settings. To change them, open Settings → Devices & services → Codex Assist and select the gear icon next to the agent. To add another agent, select Add conversation agent on the same page and give it a name, a model, and its own system prompt. It appears as its own conversation entity, such as conversation.kitchen_agent, that you can choose in any Assist pipeline. All agents share the one sign-in. The AI Task entity uses its own fixed instructions instead of a conversation prompt.

Codex Assist integration page with two conversation agents and one AI Task entity, each with its own model

Models. The chat model comes from your account's own model list. See Choosing a Model and Features and Options.

Upgrading. Upgrading from 0.5.0 or earlier keeps your settings, entity IDs, and Assist pipelines. The old integration options become the first conversation agent and the AI Task entity's settings. Older releases cannot load the upgraded entry, so take a backup first.

If a response ends before it completes, Codex Assist reports a failure. Part of the reply may already have been shown or spoken, so check a device's state before you repeat a request.

Privacy and safety

  • Codex Assist has no raw "call any Home Assistant service" bridge of its own. Every tool call goes through an LLM API that Home Assistant provides, and Home Assistant runs it. With the default Device control tools, your list of Assist-exposed entities is the practical safety boundary.
  • An agent you give the Home Assistant API can read your whole system and run any action, including on entities you have not exposed. Home Assistant allows it only for admin users. An agent you give an MCP server can use whatever that server offers. Choose these per agent, deliberately.
  • Each Assist request sends your message and the instructions Home Assistant builds for the model to the Codex service. Those instructions include an overview of your exposed entities. In Home Assistant 2026.10 the overview has names, areas, and aliases, and current states are sent only when the model asks for them. Other versions can differ. Expose only what you are comfortable sharing.
  • Keep locks, alarms, garage doors, water shutoff valves, covers, and other sensitive devices unexposed unless you want Assist to control them.
  • Hosted web search also sends the model's search queries to the Codex backend. AI Task prompts and supported attachments are sent when you run those tasks.
  • Diagnostics redact access tokens, refresh tokens, and prompts. Review them before you share them.

The security policy has the full data and control boundaries.

User guide

The GitHub Wiki is the user manual.

Project docs

About

Unofficial Home Assistant Assist agent using ChatGPT/Codex subscription access

Topics

Resources

Contributing

Security policy

Stars

26 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages