- Python 81.2%
- Shell 12.6%
- Dockerfile 6.2%
|
umrath
e0cdc19621
3.9.2: offload long-running MCP tools to threads (don't block the event loop)
FastMCP runs sync tool fns inline on its asyncio event loop (2.13.2 calls them via type_adapter.validate_python, awaiting only awaitables — no threadpool). So the long blockers froze the whole server for their duration: - ha_esphome_compile / ha_esphome_upload — up to 600s of WS log streaming - ha_watch_firmware_update — up to 600s of state polling - ha_esphome_list_devices — WS ingress session creation These four are now async wrappers that offload their (unchanged) blocking body to a worker thread via anyio.to_thread.run_sync; the server stays responsive. Verified: a fast coroutine returns in 0.05s while a 0.6s blocker runs concurrently; 35 tools still register. No new dependency (anyio ships with the MCP stack). Tests: TestBlockingToolsOffloaded (async + _offload delegation + private impl); updated esphome validation tests to target the private impls; tool-set regex now matches async tools. 464 green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|---|---|---|
| .github | 3.0.2: CI fix + server hardening — s6 smoke tests, 401 consistency, import hygiene | |
| opencode | 3.9.2: offload long-running MCP tools to threads (don't block the event loop) | |
| tests | 3.9.2: offload long-running MCP tools to threads (don't block the event loop) | |
| .gitattributes | Add README, CI workflow, and extract-boot-script | |
| .gitignore | Remove stale .coverage files, add to .gitignore | |
| CONTRIBUTING.md | Bump to 1.2.0: net_raw, .gitignore, CONTRIBUTING.md, ha addons logs | |
| LICENSE | Bump to 1.0.1: fix READMEs, add credits, fix badge note | |
| README.md | 3.8.0: reliable modern-iPad detection via touch probe | |
| repository.yaml | Reinstate badge link with .git suffix for Codeberg | |
OpenCode for Home Assistant
Run OpenCode, the open source AI coding agent, directly inside Home Assistant. Build automations, debug your config, and manage your smart home from a browser-based terminal in the HA sidebar.
App
| App | Description |
|---|---|
| OpenCode | AI assistant for automations, debugging, and smart home management |
Installation
Note: The badge link may not work with Codeberg. In that case, add manually: Settings → Apps → App Store → ⋮ → Repositories →
https://codeberg.org/umrath/hass-opencode
Features
- Web Terminal: Access OpenCode through a browser-based terminal
- Multiple LLM Providers: Use Anthropic, OpenAI, Google Gemini, and many more
- Config Access: Read and write Home Assistant configuration files
- Custom MCP Server: 35 tools for HA entity control, diagnostics, config management, logbook/calendars, and ESPHome firmware (compile/upload)
- Mobile-Aware Terminal: phones/tablets (incl. modern iPads via a touch probe) get a no-tmux, larger-font profile; desktops keep tmux
- Session Persistence: tmux integration (on by default) to preserve sessions across page refreshes
- Customizable Theme: Choose between dark and light terminal themes
- Multi-Architecture: Supports amd64 and aarch64
Quick Start
Once installed and started, open the terminal from the HA sidebar and authenticate:
# Configure your LLM provider
opencode auth login
# Start using OpenCode
opencode
Configuration Options
| Option | Description | Default |
|---|---|---|
llm_model |
Model in provider/model format. First boot only — change in opencode TUI afterwards. | anthropic/claude-sonnet-4-5 |
enable_mcp |
Enable HA integration | true |
terminal_font_size |
Font size (10-24) | 14 |
terminal_theme |
dark or light | dark |
working_directory |
Start directory | /homeassistant |
session_persistence |
Use tmux for persistent sessions | true |
enable_server |
Start opencode serve on localhost (Tailscale) | false |
server_port |
Port for server (1024-65535) | 4096 |
Supported LLM Providers
OpenCode supports 75+ LLM providers through Models.dev, including:
- Anthropic — Claude models
- OpenAI — GPT models
- Google — Gemini models
- GitHub Copilot — Log in with your GitHub account
- ChatGPT Plus/Pro — Log in with your OpenAI account
- Local models — Run models locally
Use opencode models in the terminal to see all available models.
File Locations
| Path | Description | Access |
|---|---|---|
/homeassistant |
HA configuration directory | read-write |
/share |
Shared folder | read-write |
/media |
Media folder | read-write |
/ssl |
SSL certificates | read-only |
/backup |
Backups | read-only |
Keyboard Shortcuts
| Shortcut | Command |
|---|---|
o |
opencode |
oo |
opencode --continue |
ha-config |
Navigate to config directory |
ha-logs |
View Home Assistant logs |
License
MIT License — see LICENSE.
Backup note: LLM credentials, session data, and shell history are stored in
/homeassistant/.opencode/and are included in Home Assistant backups.
Credits
This project was inspired by hass-claude by sproft, which itself builds on robsonfelix-hass-addons by Robson Felix. The CPU baseline detection, backup_exclude pattern, and AGENTS.md preservation pattern were adapted from magnusoverli/opencode by Magnus Overli (UNLICENSE). The custom MCP server (server.py) originated from mistralvibe-hass-app (Apache 2.0) and was extended with search, services, devices, safe config writing, template rendering, syntax checking, logbook/calendar/event tools, and the ESPHome firmware integration (compile/upload via HA Core's ingress proxy) adapted from magnusoverli's MCP server. The deprecation pattern database also originates from magnusoverli/opencode. The s6-overlay service architecture was adapted from mistralvibe-hass-app. Thanks to all for pioneering the Home Assistant AI assistant app pattern.