This custom integration connects Home Assistant to the hosted OpenCode Go API and exposes one native Conversation entity and one native AI Task entity. It uses the exact model IDs returned by OpenCode Go and keeps protocol and capability decisions in a reviewed local registry.
This repository is intended for HACS custom-repository installation:
- In HACS, open Custom repositories.
- Add
https://github.com/avegao/hass-opencode-gowith category Integration. - Install OpenCode Go and restart Home Assistant.
Add OpenCode Go from Settings → Devices & services → Add integration. Enter the API key from OpenCode Go, then independently enable Conversation and AI Task and choose their models. The model catalogue is loaded dynamically; labels show verified protocol and capability state. deepseek-v4-flash is the default only when it is present and verified.
Use the integration's native Reconfigure action to replace a key. The existing key is never pre-filled. Use Configure to refresh models or change entity enablement and model IDs. A configured model that disappears remains stored and is shown as unavailable; the integration never silently substitutes another model.
The Conversation entity uses Home Assistant's native Assist/LLM tool APIs only when the selected model is verified for tools. AI Task uses Home Assistant's generate_data operation for plain text and structured results. Image attachments are supported by AI Task only for verified image-capable models, and must be local JPEG, PNG, or WebP files no larger than 10 MiB each, 20 MiB total, and 4096×4096 pixels. Audio, video, PDF, remote-only files, and image generation are not supported.
The API key is stored only in the Home Assistant config entry's secret data. It is not written to model options, logs, diagnostics, test fixtures, or this repository. Requests go directly to https://opencode.ai/zen/go/v1 over HTTPS. Diagnostics contain model IDs, catalogue state, capability metadata, and whether a key is configured; they exclude the key, prompts, image bytes, authorization headers, and complete provider payloads.
Provider authentication, rate limits, quota windows, and unavailable models are surfaced as explicit errors. The integration does not retry inference requests or fall back to another model.
Normal logging reports only model-catalogue loads or changes at INFO, expected provider failures at WARNING, and malformed or unexpected integration responses at ERROR. Detailed provider and SSE timing is available at DEBUG without logging API keys, prompts, authorization headers, response bodies, generated text, or tool arguments.
Enable it temporarily in Home Assistant when investigating a provider request:
logger:
logs:
custom_components.opencode_go.provider: debugDisable debug logging after reproducing the issue. Share only sanitized log excerpts; request IDs, model IDs, timings, status codes, and stream counters are useful, but credentials and provider payloads must remain private.
Tests use sanitized fakes and do not need a production credential. Run the targeted suite with:
uv sync --group dev
PYTHONPATH=. uv run pytest --tb=short -v tests
uv run ruff check .
uv run ruff format --check .
uv run ty check --exclude testsLive OpenCode Go API smoke tests are intentionally excluded from this repository's automated validation and release gates. Deterministic tests use sanitized fakes and fixtures; any separate local smoke test must use a short-lived test secret from a developer-managed secret manager and must never place it in a file, shell history, environment file, fixture, log, CI job, or issue.
Please use issue #1 for the initial integration tracker and include sanitized logs and diagnostics only. Do not attach API keys, prompts, provider payloads, or private images.