https://github.com/dkmaker/hass-claude-code
Claude Code for Home Assistant
https://github.com/dkmaker/hass-claude-code
Last synced: 18 days ago
JSON representation
Claude Code for Home Assistant
- Host: GitHub
- URL: https://github.com/dkmaker/hass-claude-code
- Owner: dkmaker
- Created: 2026-02-12T23:02:11.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-13T08:25:41.000Z (4 months ago)
- Last Synced: 2026-02-13T08:31:31.476Z (4 months ago)
- Language: TypeScript
- Size: 884 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Claude Code for Home Assistant
A Home Assistant add-on that runs [Claude Code](https://docs.anthropic.com/en/docs/claude-code) inside your HA instance with a web terminal, full API access, and a built-in MCP server providing structured tools for interacting with your smart home.
## Features
- **Web terminal** via Home Assistant Ingress (no port forwarding needed)
- **Full HA API access** — search entities, call services, query devices/areas
- **Built-in documentation search** — HA developer and user docs indexed and searchable
- **Session persistence** — tmux keeps your Claude session alive across browser tab closes
- **MCP server** with 11 tools for Home Assistant interaction
- **Optional semantic search** — enable embeddings for AI-powered doc search
## Installation
### 1. Add the repository
[](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fdkmaker%2Fhass-claude-code)
Or manually:
1. Go to **Settings** > **Add-ons** > **Add-on Store**
2. Click the **three-dot menu** (top right) > **Repositories**
3. Add: `https://github.com/dkmaker/hass-claude-code`
4. Click **Save**, then refresh
### 2. Install the add-on
1. Find **Claude Code** in the add-on store
2. Click **Install** (the Docker image builds locally on your device — this takes a few minutes on first install)
3. Go to the **Configuration** tab and set your **Anthropic API key**
4. Click **Start**
5. Open the **Claude Code** panel in the sidebar
### How the build works
Home Assistant builds the Docker image **locally on your device** when you install the add-on. There are no pre-built images to pull. The build process:
1. Installs Node.js dependencies for the MCP server
2. Clones the HA documentation from this repository
3. Builds a keyword search index from the docs
4. Installs Claude Code CLI, ttyd, tmux, and other tools
5. Sets up s6-overlay services for process management
First install takes several minutes depending on your hardware. Subsequent updates are faster due to Docker layer caching.
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | password | *required* | Your Anthropic API key |
| `model` | string | *(empty)* | Claude model to use (leave empty for default) |
| `yolo_mode` | bool | `false` | Skip permission prompts (use with caution) |
| `enable_embeddings` | bool | `false` | Download AI model for semantic doc search (~87MB) |
| `additional_packages` | list | `[]` | Extra Alpine packages to install (e.g. `python3`, `vim`) |
## MCP Tools
The built-in MCP server (`home-assistant`) provides these tools to Claude:
| Tool | Description |
|------|-------------|
| `search_entities` | Search entities by name, domain, or area |
| `get_entity_state` | Get state and attributes of a specific entity |
| `call_service` | Call any HA service (turn on lights, run automations, etc.) |
| `search_automations` | Search automation entities |
| `get_ha_config` | Get Home Assistant core configuration |
| `list_areas` | List all defined areas |
| `search_devices` | Search the device registry |
| `get_config_entries` | List integration config entries |
| `search_docs` | Search HA developer and user documentation |
| `read_doc` | Read a specific documentation file |
| `get_doc_stats` | Get documentation index statistics |
## File Access
The add-on has access to:
| Path | Description | Access |
|------|-------------|--------|
| `/homeassistant/` | HA configuration directory (including `.storage/`) | Read/Write |
| `/config/` | Add-on configuration | Read/Write |
| `/share/` | Shared storage between add-ons | Read/Write |
| `/ssl/` | SSL certificates | Read-only |
| `/media/` | Media files | Read-only |
## Architecture
```
addon/
config.yaml # HA add-on manifest
Dockerfile # Multi-stage build
build.yaml # Base images per architecture
rootfs/ # Container filesystem overlay
etc/s6-overlay/ # s6 service definitions
usr/bin/ # Claude entrypoint script
mcp-server/ # Node.js MCP server
src/
index.ts # MCP entry point (stdio transport)
ha-api.ts # HA REST API tools
ha-websocket.ts # HA WebSocket API tools
docs-search.ts # Documentation search tools
db.ts, search.ts, embeddings.ts, indexer.ts # Search engine
```
The MCP server runs as a stdio child process of Claude Code (configured via `.mcp.json`). No separate network port needed.
## Development
To test locally without HA:
```bash
# Build the Docker image
docker build -t claude-code-addon addon/
# Run with your API key
docker run -it \
-e SUPERVISOR_TOKEN=fake \
-e ANTHROPIC_API_KEY=your-key \
claude-code-addon
```
## Supported Architectures
- `amd64` (x86_64)
- `aarch64` (ARM64, e.g. Raspberry Pi 4/5)