A Language Server Protocol (LSP) implementation for Home Assistant that provides intelligent code assistance for any LSP-compatible editor (Neovim, VSCode, Emacs, Sublime Text, etc.).
- Auto-completion: Entity IDs, service calls, and domain names
- Hover Information: Real-time entity state and attributes
- Dashboard Commands: Edit Lovelace dashboards via custom LSP commands
- Multi-editor Support: Works with any LSP-compatible editor
npm install -g homeassistant-lspOr install locally:
git clone https://github.com/myakove/homeassistant-lsp.git
cd homeassistant-lsp
npm install
npm run buildIf you want to test the LSP server before installing globally:
-
Clone and build:
git clone https://github.com/myakove/homeassistant-lsp.git cd homeassistant-lsp npm install npm run build npm test # Verify all tests pass
-
Test with Neovim (local path):
local lspconfig = require('lspconfig') local configs = require('lspconfig.configs') if not configs.homeassistant then configs.homeassistant = { default_config = { -- Use local build instead of global install cmd = { 'node', vim.fn.expand('~/git/homeassistant-lsp/dist/server.js'), '--stdio' }, filetypes = { 'yaml', 'yaml.homeassistant', 'python' }, root_dir = lspconfig.util.root_pattern('.git', 'configuration.yaml'), settings = { homeassistant = { host = 'ws://homeassistant.local:8123/api/websocket', token = 'your-long-lived-access-token', }, }, }, } end lspconfig.homeassistant.setup({})
-
Verify it works:
- Open a YAML or Python file
- Type
entity_id: sensor.and check for completions - Hover over an entity ID to see info
Once verified, you can install globally with npm install -g . from the project directory.
The LSP server requires connection details to your Home Assistant instance:
homeassistant.host(required): WebSocket URL (e.g.,ws://homeassistant.local:8123/api/websocket)homeassistant.token(required): Long-lived access token
The LSP server supports environment variable overrides for configuration:
HA_HOST- Home Assistant WebSocket URLHA_TOKEN- Long-lived access tokenHA_TIMEOUT- Request timeout in milliseconds (default: 5000)LOG_LEVEL- Logging level: DEBUG, INFO, WARN, ERROR (default: INFO)
Example:
export HA_HOST="ws://192.168.1.10:8123/api/websocket"
export HA_TOKEN="your_token_here"
export LOG_LEVEL="DEBUG"
nvim configuration.yamlThese override values provided in the LSP client settings.
-- In your Neovim config (e.g., ~/.config/nvim/lua/lsp/homeassistant.lua)
local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')
-- Define the custom server
if not configs.homeassistant then
configs.homeassistant = {
default_config = {
cmd = { 'homeassistant-lsp', '--stdio' },
filetypes = { 'yaml', 'yaml.homeassistant', 'python' },
root_dir = lspconfig.util.root_pattern('.git', 'configuration.yaml'),
settings = {
homeassistant = {
host = 'ws://homeassistant.local:8123/api/websocket',
token = 'your-long-lived-access-token',
},
},
},
}
end
-- Setup the server
lspconfig.homeassistant.setup({
on_attach = function(client, bufnr)
-- Your on_attach function
end,
})VSCode support requires a separate extension (coming soon). For now, you can use the server directly with the VSCode extension development workflow.
Once configured, the LSP server provides:
Type entity_id: followed by a domain name to get entity suggestions:
automation:
- trigger:
platform: state
entity_id: sensor. # <-- Completion triggers hereHover over any entity ID to see its current state and attributes:
entity_id: sensor.temperature # <-- Hover here for infoUse LSP commands to manage dashboards:
homeassistant.listDashboards- List all editable dashboardshomeassistant.getDashboardConfig- Get dashboard configurationhomeassistant.saveDashboardConfig- Save dashboard changes
The LSP also works with Python files for AppDaemon automations:
# In your AppDaemon apps
import appdaemon.plugins.hass.hassapi as hass
class MyApp(hass.Hass):
def initialize(self):
# Completion works here
self.get_state("sensor.") # <-- Completion triggers
self.call_service("light.") # <-- Completion triggers
# Hover works too
temp = self.get_state("sensor.temperature") # <-- Hover for entity infoSupported Python patterns:
get_state("entity_id")- Auto-completion and hovercall_service("domain.service")- Service completionset_state("entity_id")- Entity completion- Template strings:
f"The temperature is {self.get_state('sensor.temp')}"
The LSP detects entity IDs in:
- Function call arguments
- String literals
- F-strings and format strings
-
Check LSP is running:
# In Neovim :LspInfoYou should see
homeassistantclient attached. -
Check connection to Home Assistant:
:lua vim.lsp.buf.execute_command({command='homeassistant.getConnectionStatus'})
-
Check LSP logs:
Neovim LSP logs location:
~/.local/state/nvim/lsp.logtail -f ~/.local/state/nvim/lsp.logEnable debug logging:
vim.lsp.set_log_level("DEBUG")
- Ensure you're in a YAML or Python file
- Try manual trigger: Type
entity_id:and press<C-Space> - Check if LSP server is connected to Home Assistant (see above)
- Verify completion is enabled in your LSP client config
"Entity not found" errors for valid entities:
- The entity might not be loaded yet - try reloading cache:
:lua vim.lsp.buf.execute_command({command='homeassistant.reloadCache'})
- Check if entity is actually available in Home Assistant
High CPU/memory usage:
- Large entity lists can impact performance
- Consider adjusting cache TTL in configuration
- Check for rapid document changes triggering constant validation
WebSocket connection errors:
- Verify the WebSocket URL is correct (should start with
ws://orwss://) - Check if Home Assistant is accessible from your machine
- Verify the long-lived access token is valid
- Check firewall settings
# Install dependencies
npm install
# Build the project
npm run build
# Watch mode for development
npm run dev
# Run tests
npm test
# Run with coverage
npm run test:coverage
# Lint code
npm run linthomeassistant-lsp/
├── src/
│ ├── server.ts # Main LSP server entry point
│ ├── ha-client.ts # Home Assistant WebSocket client
│ ├── cache.ts # Entity/service caching layer
│ ├── providers/
│ │ ├── completion.ts # Completion provider
│ │ └── hover.ts # Hover provider
│ ├── utils/
│ │ ├── logger.ts # Logging utility
│ │ └── config.ts # Configuration management
│ └── types/
│ └── homeassistant.ts # Type definitions
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── fixtures/ # Test fixtures
└── docs/ # Documentation
The LSP server consists of several key components:
- LSP Server Core: Handles LSP protocol communication
- WebSocket Client: Connects to Home Assistant API
- Caching Layer: Caches entities and services for fast lookups
- Providers: Implement LSP features (completion, hover)
See ARCHITECTURE.md for detailed architecture documentation.
Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
MIT
- Home Assistant - Open source home automation
- LSP Specification - Language Server Protocol
- Issues: GitHub Issues
- Discussions: GitHub Discussions