Skip to content

Features and Options

itsreverence edited this page Nov 16, 2026 · 13 revisions

Features and Options

Codex Assist has two Home Assistant surfaces: one or more Assist conversation agents, and an AI Task provider. They share one signed-in connection but return different Home Assistant result types.

Assist conversations

Select Codex Assist as the conversation agent in an Assist pipeline. See Installation. It can:

  • answer normal text or voice prompts;
  • stream text while the model is responding;
  • read the state of exposed entities;
  • request simple actions through Home Assistant's native Assist LLM API;
  • use hosted web search when you turn it on.

Home Assistant's list of entities exposed to Assist controls device access. Codex Assist does not add a raw service-call bridge. See Safe Entity Exposure.

Hosted web search

Hosted web search is off by default. Turn it on in a conversation agent's or the AI Task entity's settings when you want the model to answer questions about current information.

When search is used:

  • the current model turn, the conversation context, the model's search queries, and the Home Assistant country setting go to the Codex backend;
  • retrieved results stay available to the model across tool calls and follow-up questions;
  • the integration asks the model to keep raw URLs, markdown links, and source sections out of speech and to name sources in plain words, without guaranteeing that it complies.

Since 0.5.0, search answers no longer include hidden "Sources" data in response.card.

Search is disabled for AI Tasks that ask for structured data, so the output keeps its shape. The search endpoint is undocumented and can change upstream. There is no setting to choose between search implementations.

AI Task

Codex Assist registers a native Home Assistant AI Task provider. Depending on the automation or integration that calls it, it can return:

  • plain generated text;
  • structured data validated against a schema you supply;
  • a generated image;
  • answers based on supported image attachments.

Attachments belong to AI Task actions and surfaces that accept them. A normal Assist chat may not show an upload button. Image attachments are limited to four files, 10 MiB per file, and 20 MiB in total. An unreadable or oversized image sent with nonblank instructions fails the request before it reaches the model. Non-image attachments are ignored.

Run a data task

The ai_task.generate_data action returns its result as a response, so store it with response_variable. This example asks for one structured field. Use it as an action in a script or automation.

action: ai_task.generate_data
data:
  task_name: Status summary
  entity_id: ai_task.codex_assist_ai_task
  instructions: Write one short sentence saying that everything looks fine.
  structure:
    summary:
      description: One short sentence
      required: true
      selector:
        text: {}
response_variable: status_result

ai_task.codex_assist_ai_task is an example. Replace it with the entity ID of your own Codex Assist AI Task entity, or leave out entity_id if you have chosen a preferred AI Task entity in Home Assistant. In later actions, read the field as {{ status_result.data.summary }}. Without structure, the result is plain text in {{ status_result.data }}. For the full list of fields and selectors, see Home Assistant's AI Task documentation.

Agent and AI Task settings

Since 0.6.0, each conversation agent and the AI Task entity keep their own settings. Open Settings → Devices & services → Codex Assist and select the gear icon next to the agent or the AI Task entity. Each form keeps everyday controls visible and collapses the less common groups.

Add another conversation agent

Select Add conversation agent on the same page. Give it a name, a chat model, and its own system prompt. It appears as its own conversation entity, such as conversation.kitchen_agent, which you can choose in any Assist pipeline. All agents share the one sign-in. To remove an agent, delete it from its three-dot menu.

Everyday settings

  • Chat model chooses from the models your account returns. Cached results and unverified fallback suggestions are labeled, and a saved model that is no longer listed stays selected until you replace it. See Choosing a Model.
  • Response length guides how concise or detailed normal text and voice answers should be.
  • Hosted web search allows searches for current information. It is off by default. Turning it on changes what can leave Home Assistant for a request, so read the security policy.

Advanced chat settings

  • System prompt sets standing instructions for that conversation agent. Its multiline editor supports longer Markdown prompts. Start with the default and add only the guidance you need. The AI Task entity has no system prompt. It uses fixed AI Task instructions.
  • Reasoning effort controls how much reasoning a supported model should use. Higher effort can take longer or use more of the account's allowance.
  • Home Assistant tools chooses which tool sets the agent may use. See Home Assistant tools below. Since 0.7.0.

The backend reasoning-summary setting is not shown, because Codex Assist does not expose that summary as a useful Home Assistant result. Existing stored values still work.

Home Assistant tools

Since 0.7.0, each conversation agent chooses which of Home Assistant's LLM APIs it may use. Open the agent's gear icon and expand Advanced chat settings. The Home Assistant tools list shows every tool set Home Assistant has registered:

  • Device control is Home Assistant's Assist API, the tools every agent had before 0.7.0. The agent reaches only the entities you expose to Assist. New and existing agents keep this choice unless you change it.
  • Home Assistant is Home Assistant's own diagnostics and management API, added in Home Assistant 2026.11. It can read your whole system, including entities you have not exposed, render templates, and run any action. Home Assistant offers it only when an admin user makes the request.
  • Each MCP server you connect through Home Assistant's Model Context Protocol integration appears under the name that server reports. The agent can use whatever that server offers, and the results go to Codex.

Select several to combine them, or clear every choice for a chat-only agent with no tools. Home Assistant merges the selected tool sets, checks admin-only access, and runs every tool call. Codex Assist adds no service-call path of its own.

Give the wider tool sets to a separate agent, for example an admin agent you use from the Home Assistant app, rather than your everyday voice agent. Voice satellites usually make requests without an admin user, so Home Assistant refuses the Home Assistant tool set there. See Troubleshooting.

Codex Assist leaves out tools that Codex cannot call: names with characters other than letters, digits, _ and -, names over 64 characters, and a tool named web_search while hosted web search is on. Each skipped tool is logged at debug level for custom_components.codex_assist.

If you remove an MCP server or another integration that provided a selected tool set, the choice stays saved and is labeled "saved; not currently available" until you clear it.

AI Task entities offer Codex no Home Assistant tools.

Image-generation defaults

These belong to the AI Task entity.

  • Image quality sets the default quality for AI Task image generation.
  • Image size chooses square, landscape, or portrait output.

The values match the request shapes the integration supports.

Shared sign-in

Every conversation agent and the AI Task entity share one config entry and one token coordinator. If OpenAI invalidates the sign-in, Home Assistant offers to sign in again. You never paste a token.

Behavior notes

These notes describe how replies behave and which release introduced each behavior.

  • Completed responses. Since 0.4.9, the backend must confirm that a response is complete before Codex Assist reports success or runs the tool calls the model proposed. Text can still stream before completion. An interrupted response cannot undo text already delivered or actions from earlier completed responses, and incomplete generated images are not saved.
  • Recovered text. Since 0.4.10, Codex Assist can recover missing answer text from completed assistant messages when it can match that text to the stream. Silent, ambiguous, or conflicting responses fail explicitly.
  • Clarifying questions. Codex Assist asks the model to put one concise clarifying question last, with nothing after it. Home Assistant decides whether a reply continues the conversation. In the versions that were tested, the reply must end in ?, ASCII ; (U+003B), or fullwidth ?. Other punctuation, including Arabic ؟, does not trigger that check. The model may not comply, and a physical satellite may not listen again. See Troubleshooting.
  • Error speech. Caught failures use short, fixed replies. General failures say "Sorry, I couldn't complete that." Failures that start reauthentication say "Codex Assist needs attention in Home Assistant." Account or usage limits say "Codex Assist cannot process this request because of an account or usage limit." Authentication failures that do not start reauthentication, attachment validation failures, and history-limit failures use the general reply. The model is also asked to skip unsolicited technical details. That request does not filter model replies or Home Assistant tool results. AI Task errors are unchanged.