Skip to content
magnusoverliPublic

About

No description, website, or topics provided.

Resources

Stars

471 stars

Watchers

6 watching

Forks

Repository files navigation

🚀 OpenCode

AI-Powered Configuration Assistant for Home Assistant

Stable Release Beta Release Project Stage License Maintenance

Transform your Home Assistant configuration with the power of AI

Getting Started • Features • Documentation • Support


Upstream attribution: This is an independent Home Assistant add-on that redistributes and integrates OpenCode, © 2025 opencode, under the MIT License. It is not made by, affiliated with, or endorsed by the OpenCode team or Anomaly. See the third-party notices.

🚀 Getting Started

Install OpenCode for the stable channel, or OpenCode Beta to test upcoming changes. See the stable changelog and beta changelog for current versions and bundled component updates.

This is a Home Assistant Supervisor add-on (called an app in newer Home Assistant versions), not a standalone Home Assistant Core/Container integration. It supports amd64 and aarch64/ARM64.

Stable 3.5.1 includes OpenCode 2.3.0, OpenChamber 2.7.2 and HAB 1.8.0. Upgrading an existing installation? Back up first and read the 3.5.1 upgrade notes, including stable history preservation and backup-based rollback. Coming from 2.x? Follow the 2.x upgrade guide.

⚙️ Hardware requirement: x86-64 CPUs need SSE4.2, and the regular build also requires AVX2. SSE4.2 alone may not be sufficient: the documented upstream baseline-package issue can still prevent non-AVX2 CPUs from running OpenCode. ARM64 is unaffected by these x86 requirements. See CPU requirements before installing on older hardware or a VM.

1. Add This Repository

Add Repository

Or add manually

Go to Settings → Apps → Install app → ⋮ → Repositories. On older Home Assistant versions, use Add-ons → Add-on Store instead.

Add: https://github.com/magnusoverli/opencode

2. Install the Add-on

Find "OpenCode" in the app/add-on store and click Install.

💡 Prefer the beta channel to try new features early? Install "OpenCode Beta" from the same repository instead — it installs side by side with the stable add-on. See Release channels.

3. Open OpenCode

Start the add-on, then click Open Web UI (or use the sidebar entry). By default you'll land in a web terminal.

💡 Prefer a graphical interface? Set Interface (interface_mode) to openchamber in the add-on Configuration tab and restart to use the OpenChamber web UI on the same sidebar entry. Both interfaces use the same managed OpenCode V2 backend and conversation history within that channel.

4. Connect an AI Provider

The web terminal opens OpenCode automatically. Enter /connect and follow the provider's sign-in prompts, then /models to choose a model. In OpenChamber, use its provider/model settings instead. Anthropic, OpenAI, Google and other cloud or local providers are supported; credentials, subscriptions and usage charges depend on the provider.

OpenCode and OpenChamber are pinned in the add-on image. Update them through Home Assistant Supervisor, not an upstream in-app updater.

5. Try It

Once connected, ask OpenCode things like:

# Create a new automation
"Create an automation that turns on lights when motion is detected"

# Review your configuration
"Check my configuration.yaml for any issues"

# Add sensors
"Add a template sensor to track my total energy usage"

# Get entity information
"What's the current state of all my lights?"

# Troubleshoot
"Why isn't my bedroom motion sensor triggering automations?"

# Analyze history
"Show me temperature trends for the past 24 hours"

🎯 Features

OpenCode brings the OpenCode AI coding agent directly into your Home Assistant instance. Experience intelligent configuration editing through natural language, advanced YAML assistance, and deep integration via the Model Context Protocol (MCP) — with a growing set of features that help it understand your installation, not just configuration syntax in general.

🤖 AI-Powered Editing

Use natural language to modify your Home Assistant configuration. No more searching documentation - just ask!

🎨 Two Interface Modes

Choose a web terminal with 10 themes or the graphical OpenChamber web UI through Home Assistant Ingress. Both share one backend and history within a channel. Optional LAN frontends require separate authentication and a trusted HTTPS reverse proxy; mapping a port alone is not enough. The OpenCode LAN API also supports device pairing and individual revocation. See LAN setup.

🔌 Provider Agnostic

Works with Anthropic, OpenAI, Google, other cloud providers and OpenAI-compatible local servers. Available models and authentication methods depend on the bundled runtime and provider.

🔐 Private TEE Models (Beta)

Opt-in PPQ support uses an attested encrypted transport for eligible private models. Configure a PPQ key and explicitly select a private model; enabling it does not switch existing sessions. Account-backed encrypted inference remains unverified. See PPQ setup.

🎚️ Scoped MCP Tool Profiles

Choose compact, configuration, or full (full is the default) to reduce the bundled MCP tool surface and prompt size. Hidden tools are rejected, but profiles do not restrict shell or filesystem access. See tool profiles.

🔎 Read-Only Investigations

Select home-assistant-read-only through /agents for file reads, compact diagnostics and non-applying Supervisor previews. Its managed policy denies edits, shell commands and native HA tools. Applying a reviewed app plan requires an apply-capable agent such as Build and the full profile. See read-only sessions.

🔧 Deep MCP Integration

Bundled tools, resources and guided prompts cover state and service calls, history, config validation, calendars, decision notes, updates, ESPHome, Supervisor diagnostics and CLI gateways. ha-mcp tools lists the server's advertised tools; get_agent_capabilities also reports the current agent's offered tools when a fresh runtime snapshot is available. Tool availability does not itself grant permission to execute a call.

🎛️ Supervisor App Review

Inspect apps by display name, review redacted options and before/after changes, and preview option or lifecycle operations without applying them. Applying a single-use, five-minute plan requires the full profile, an apply-capable agent and native permission approval. See Supervisor app management.

🧠 Home Context

Sessions start knowing your installation instead of rediscovering it. A generated briefing describes your setup, AGENTS.local.md holds your own standing instructions that survive updates, and decision notes — recorded only with your approval — carry the reasoning behind your configuration between sessions. Inspect it all with ha-context.

💡 Intelligent LSP Support

Home Assistant YAML diagnostics, completions, hover and definitions are available through agent tools, with live diagnostics/completion in OpenChamber's Ingress editor. Whole-file YAML formatting is opt-in. See language assistance.

🛡️ Safe Config Writing

Use write_config_safe for complete YAML files or patch_config_safe for reviewed exact-text changes that preserve surrounding content. Both use revision checks, atomic replacement, recovery copies and post-save HA validation. Editor-managed automations, scripts and scenes use their supported editor APIs. See reviewed YAML transactions.

🏗️ hab CLI Integration

Includes the Home Assistant Builder CLI by @balloob for dashboards, registries, helpers, backups and administration. Agents use the authenticated hab_run MCP gateway in the full profile; their shell does not inherit Supervisor credentials. A separately permissioned hab_run_read_only gateway enforces a limited dashboard/helper read subset, also in full.

🧩 Startup Hooks

An opt-in, persistent place for your own scripts to run at add-on startup. Scripts run as root; keep customizations in the supported startup hooks directory, not the disposable container filesystem.

🧭 Native HA Tools & Experimental Assist

Connect to Home Assistant's native MCP tools independently of bundled tools. An optional experimental companion also lets HA use OpenCode for Assist conversations and AI data tasks. These are separate integrations; see setup and requirements.


🌟 What is OpenCode?

OpenCode is an open-source AI coding agent that transforms how you interact with your codebase. It understands your files, executes commands, and helps you build and maintain software using natural language.

Think of it as your personal expert developer who:

  • 📖 Reads relevant configuration files and inspects live state through tools
  • ✏️ Suggests and implements improvements
  • 🐛 Helps diagnose bugs and apply approved fixes
  • 🚀 Implements new features on request
  • 💬 Explains complex configurations in plain English

🎭 Supported AI Providers

OpenCode supports cloud providers and local models. Choose a provider and model that support tool calling and fit your hardware, privacy needs and budget:

🔥 Popular Providers (Click to expand)
Provider Notes
🧠 Anthropic Claude models — recommended for configuration work
💎 OpenAI OpenAI models with supported API-key or subscription sign-in
🌈 Google Gemini models
☁️ AWS Bedrock Claude, Llama, Mistral, and others via AWS
🔷 Azure OpenAI Azure-hosted OpenAI models
🐙 GitHub Copilot GitHub sign-in; requires an eligible Copilot account
⚡ Groq Ultra-fast inference for open models
🎯 Mistral Mistral and Codestral models
🦙 Ollama Local models — see the context-window and tool-profile guidance before choosing hardware
🌐 OpenRouter Models from multiple providers through a single API
🤝 Together AI Hosted open-weight models
🔥 Fireworks AI Fast inference for open models
🚀 xAI Grok models
💫 DeepSeek DeepSeek models

Running models locally? The add-on sends a large tools-and-instructions prompt on every request. Read the context-window and tool-profile guidance first — a small model on modest hardware can take minutes per reply. A smaller MCP tool profile (see Features) is one of the easiest ways to cut that cost.

💳 Model access and costs

The add-on does not include a paid model subscription. Upstream may offer free models, but availability, limits and terms can change; do not assume every model offered through OpenCode is free or keyless. Check the provider's current pricing and OpenCode's provider documentation.

For browser-based provider sign-in in OpenChamber, follow the sign-in handoff guide. For a separate local inference server, see the custom-provider examples.

Your prompts and tool results are sent to the selected model provider. Local models need a separately running inference server; the add-on itself is not one.


🛡️ Safety & Validation

This add-on has read/write access to your Home Assistant configuration directory.

It also mounts Home Assistant add-on development folders (/addons and /addon_configs) so OpenCode can help with custom add-ons. Treat /addon_configs as sensitive because it may contain configuration data for other add-ons.

The bundled write_config_safe and patch_config_safe MCP tools share a validation and recovery pipeline. These checks apply to writes through those tools, not every file write:

  • 🔎 Review before applying — preview first, then approve the proposed content. Whole-file writes require the preview's source revision; patches also require its candidate hash. Stale revisions are rejected
  • 🔐 Coordinated writes — atomic replacement and a shared writer lock protect cooperating app writers. Unrelated external editors are not covered by an atomic compare-and-swap
  • 🔍 HA config validation — after writing, the tool runs HA Core's config check; a failed or unavailable check is not reported as a successful save
  • ↩️ Backup and recovery — unique recovery copies and journals are retained in /homeassistant/.opencode-safe-write-backups/. On failed validation, the tool attempts to restore the original or remove an invalid new file. Only restored confirms verified restoration; an uncertain outcome requires inspection. Keep independent backups
  • 🧪 Jinja2 template pre-validation — checks changed templates through HA's engine where possible; unchanged or runtime-dependent templates can be skipped
  • 📋 Deprecation scanning — checks for outdated syntax and cross-checks your instance's HA Repairs warnings
  • ✂️ Guardrails against accidental data loss — large deletions (missing list entries, removed top-level keys, or a file shrinking by more than half) are blocked unless explicitly confirmed
  • 🏥 HA Repairs integration — surfaces your installation's active deprecation warnings
  • ⚠️ Structural checks — catches missing triggers, actions, and other required fields

Other guardrails and their limits:

  • ✅ Direct-edit approval — native file edits and configured shell patterns (yq -i, sed -i, tee, rm, mv) ask by default. These rules do not detect every possible shell write, and approval does not run safe-write validation. The YAML write tools have no separate managed native edit prompt; agent instructions still require your consent. Supervisor app apply has its own mandatory native permission prompt
  • 🔒 Sensitive-file read protection — the normal agent's read tool denies secrets.yaml, .storage/, .cloud/, ssl/, *.key/*.pem, and safe-write recovery files by default. This is not a shell sandbox: allowed shell commands run as container root and can bypass read-tool restrictions. See protection scope
  • 🔄 Saved is not active — neither YAML write tool reloads Home Assistant. Apply an approved domain reload or restart as appropriate, then verify loading. The configuration profile omits service calls, so reload remains a manual step. Editor-API saves can activate automatically; consent must cover that behavior. See editing automations

Additional best practices:

  • 💾 Always backup your configuration before significant changes
  • 👀 Review changes suggested by the AI before accepting them
  • 📝 Use version control (git) when possible for easy rollback

🧭 Home Assistant Native Integration

Home Assistant's native llm platform and keyed MCP endpoints are available from HA 2026.8. The add-on supports several distinct connections:

  • Bundled Home Assistant tools (mcp_enabled) provide the add-on's configuration, validation, diagnostics and administration surface independently of HA's MCP Server.
  • Home Assistant native tools (native_ha_mcp_enabled) connect OpenCode to HA's own MCP Server. On HA 2026.10+, enable it under Settings → System → AI → Model Context Protocol; on older versions, add the Model Context Protocol Server integration. Review the add-on's native settings and restart it.
  • Expose read-only MCP to Home Assistant (ha_mcp_server_enabled) is an opt-in reverse connection, sharing the add-on's read-only tools with HA. See read-only sharing.
  • OpenCode Assist (ha_assist_enabled) is an experimental, default-off companion for HA 2026.10–2026.11 with Supervisor. Enable it and restart the add-on, then restart Home Assistant Core to load the companion and configure the discovered integration. Choose a model and AI tools explicitly. Voice also needs separate speech engines; full supervised voice-pipeline and crash-recovery qualification remain open. See Assist setup.

Native bridge defaults: native tools are on for new installs and use Your MCP API (/api/mcp); upgrades preserve effective enabled/disabled state and migrate legacy Assist selections once. home_assistant, assist and custom selections are available. /api/mcp follows HA's selected APIs and can expand when Expose all LLM APIs is on. The add-on does not enable or reconfigure HA's MCP Server. No URL or token needs copying. Review migration and rollback guidance.

On HA 2026.11, the MCP Server's Read-only setting applies to the configured /api/mcp endpoint, not independently selected /api/mcp/<ID> endpoints or the Assist companion's directly selected AI tools. Review the selected API's access scope; administrator tools are not limited to entities exposed to Assist.

Bundled, native and external MCP connections activate independently. A connected status alone does not prove native tools have loaded: verify a suitable read-only tool. Native tools complement, rather than replace, the bundled safe-write and administration workflows.

Stable and beta have separate histories and settings, but edit the same HA configuration. Only one channel should manage the shared Assist companion; follow the ownership-switch instructions when moving between them.


📚 Documentation

Comprehensive documentation is available covering all features:


🤝 Support

Need help? We've got you covered:

💬 Discord

Join OpenCode Discord

Upstream OpenCode community; use this repository's issues for add-on problems

📖 Documentation

OpenCode V2 Docs

Upstream guides; add-on-specific setup is in our documentation

🐛 Issues

GitHub Issues

Bug reports & feature requests


🌟 Contributing

Reproducing CI

On Linux with Bash, Node 24/npm, Python 3, Git, a C compiler (cc), Chrome and Docker available:

bash scripts/ci-checks.sh beta contracts
bash scripts/ci-checks.sh beta image

Use stable for the stable channel. The contracts command installs the pinned dependencies, audits them, and runs the channel's tests and root-boundary checks (using sudo when needed). Set HA_ASSIST_BROWSER_EXECUTABLE for a different Chrome/Chromium path. The image command explicitly builds boundary-test; an ordinary Docker build does not run that stage. Use an LF checkout for Linux builds: hash-checked compatibility files and fixtures must retain their committed bytes.

CI selects the affected channels. Shared changes exercise both, in independent jobs, so a stable failure does not hide beta results. Contract logs are retained as workflow artifacts; native AMD64/ARM64 image checks retain their build records.

We love contributions! Here's how you can help:

  1. 🍴 Fork the repository
  2. 🔧 Create your feature branch (git checkout -b feature/amazing-feature)
  3. 💾 Commit your changes (git commit -m 'Add amazing feature')
  4. 📤 Push to the branch (git push origin feature/amazing-feature)
  5. 🎉 Open a Pull Request

Contributions of all kinds are welcome — feel free to open a PR!

Release channels

Channels are folders, not branches. Both live on main:

  • ha_opencode/ — the stable channel. Tagged v*, published as the OpenCode add-on.
  • ha_opencode_beta/ — the beta channel, for work still soaking. Tagged beta-v*, published as the OpenCode Beta add-on.

Each folder is a complete add-on with its own Dockerfile and rootfs/, so a stable release cannot contain something that only exists in beta. Put experimental work in ha_opencode_beta/; change ha_opencode/ when preparing a stable fix or promoting validated beta work. Merging does not publish an image; the release workflows build and publish the tagged channel.

Both add-ons can be installed side by side — they keep separate decision notes and app storage, but share Home Assistant configuration files and AGENTS.local.md. Installing the other channel does not transfer conversations or provider sign-ins. Use different host ports if exposing both channels' LAN frontends, and only one channel to manage the shared Assist companion.

Home Assistant development

The devcontainer is the default local development environment. It runs the add-ons under Home Assistant's official Supervisor development environment. Run the Start Home Assistant task first, then use the install, rebuild, start, and log tasks for either ha_opencode or ha_opencode_beta. On a first run, use Install App followed by Start App; use Rebuild and Start App while iterating, and run Run App Acceptance after runtime or lifecycle changes. The install task first registers the app, then builds the working tree over its local image tag; rebuilds stop the app before replacing that tag. Acceptance traverses Home Assistant Core's real Ingress route and, for beta, verifies automatic s6 recovery after a sidecar crash. Native amd64 and arm64 boundary checks run in GitHub Actions; a local emulated arm64 build is not a release gate.


👏 Contributors

Thank you to everyone who contributes code, reports issues, tests releases or improves the documentation!

Contributors to this repository

View contributors on GitHub. The avatar image is automatically generated from GitHub contributor data by contrib.rocks, not maintained as a separate list in this repository. The stable and beta changelogs also credit reports and suggestions.

Upstream acknowledgements

This add-on builds on OpenCode, OpenChamber and @balloob's hab CLI, among other open-source projects. See third-party notices for retained license and attribution information.


📜 License

This is free and unencumbered software released into the public domain - see the UNLICENSE file for details.

This distribution also includes third-party software, including OpenCode. Its copyright notices and license terms are retained in THIRD-PARTY-LICENSES.md and in the add-on image at /usr/share/doc/ha-opencode/NOTICE.


⭐ If you find OpenCode helpful, please star this repository!

Made with ❤️ for the Home Assistant community

Getting Started • Features • Documentation • Support

About

No description, website, or topics provided.

Resources

Stars

471 stars

Watchers

6 watching

Forks

Releases

Packages

Contributors

Languages