Claude Terminal Pro for Home Assistant

Claude Code inside your Home Assistant sidebar. A browser terminal with the tools you need for HA work, a session that survives restarts, and a side panel to see, check and undo what Claude changed.

📖 Documentation · Changelog · Development guide

What's new

• 2.4.8: Home Assistant status line. Context, tokens and plan limits, plus the home under Claude's prompt: alerts, repairs, broken automations, old backups, a full disk and updates, only when they need a look. Pick the pieces in the options, or make your own with /statusline.
• 2.4: voice and mobile terminal improvements. Home Assistant speech-to-text, phone keys, Shift+Enter, larger uploads through ingress and reliable terminal startup. Version 2.4.7 also removes deprecated build metadata.
• 2.3: Changes tab. See exactly what Claude changed in /config, line by line, undo any file with two clicks, and accept the rest as a checkpoint. It uses a local git repository and can create one for you.
• 2.2: Files sidebar. A tree of /config, a Recent changes list showing what Claude just edited, and a button that runs Home Assistant's config check before you restart. It sits on the right and collapses to a thin rail.
• 2.1: community release. New installs build in seconds again. Copy and paste work properly, including on phones. The session picker no longer freezes after a crash. New options: init_commands, working_directory, enable_remote_control, claude_code_oauth_token and claude_extra_args. Security is tighter too: ingress only by default.

Full history in the changelog.

Important

Updating from 2.0.x? Ports 7680 and 7681 are now closed by default, because both served a root shell with no login. The sidebar panel works exactly as before. If you opened the terminal at http://<ha>:7681, set the port again under the add-on's Network settings, and read Security first.

Install

You need a Claude subscription that includes Claude Code, or an Anthropic Console account with API billing. Claude Code isn't included in the free Claude plan. See Claude Code account requirements.

1. Click the button above, or go to Settings → Add-ons → Add-on Store → ⋮ → Repositories and add https://github.com/esjavadex/claude-code-ha
2. Install Claude Terminal Pro and start it
3. Open Claude Terminal Pro from the sidebar and log in to Claude when asked

Claude's login link also shows up as a Home Assistant notification (and in the Companion app), so you can open it with one tap. With a Claude plan, no API key is needed.

Features

Terminal

• Claude Code in a web terminal embedded in the HA sidebar, starting in /config
• A persistent tmux session: close the tab or restart HA Core and you reattach to the same conversation
• An optional session picker: new, continue, resume, custom flags, auth helper, gh login, bash
• Copy and paste that work: mouse selection, Claude's /copy, Copy and Copy link buttons, swipe to scroll on touch screens
• Paste, drop or upload images and other files (PDFs, text, YAML, logs…) for Claude to read
• Shift+Enter for a new line, and on phones a row of the keys Claude Code needs above the on-screen keyboard
• Voice input: dictate, review, then insert at the prompt without sending. Uses your Home Assistant speech-to-text engine where the browser has none (Firefox, some Companion app WebViews)
• A status line under Claude's prompt: context, plan limits, and anything in the home that needs a look

Files sidebar

• A read-only tree of /config with previews. Insert path types a file's path at the prompt
• Recent changes: files changed in the last hour, day or week
• ± Changes: a coloured diff of everything changed since the last checkpoint, with Revert file and Accept all changes (local git, never pushed)
• ✓ Check HA configuration runs ha core check

Home Assistant tooling

• The ha and gh CLIs, git, Python 3, Node.js, jq, yq, vim, nano and tree are included
• Access to the Supervisor and Core APIs, plus Claude skills and commands for HA work
• Remote Control: drive the same session from the Claude app or claude.ai/code

Persistence

• Login, settings, history and packages live in the add-on's /data and survive restarts and updates
• persist-install for APK and pip packages that survive reboots, plus auto-install lists in the config
• init_commands to start your own scripts or services on every boot
• Optional persistent Claude install with an Update Claude Code option in the session picker
• Lean backups: caches and files that can be downloaded again are left out

Configuration

Option	Default	What it does
auto_launch_claude	true	Start Claude straight away, or show the session picker
working_directory	/config	Folder the terminal and Claude start in
claude_code_oauth_token	empty	Long-lived token from claude setup-token, instead of the browser login
enable_remote_control	false	Also expose the session in the Claude app and at claude.ai/code
claude_extra_args	empty	Extra flags for every launch, e.g. --model claude-sonnet-5-5 (quoting works)
dangerously_skip_permissions	false	Let Claude run tools without asking. Read Security first
tmux_mouse	false	tmux mouse mode. Keep it off for native browser copy and paste
persistent_apk_packages	[]	Alpine packages installed on every start
persistent_pip_packages	[]	Python packages installed on every start
init_commands	[]	Shell commands run on every start, after packages (120 s each)
use_persistent_claude	false	Use a Claude Code install kept in /data/npm
auto_update_claude_on_start	false	Update that persistent install on every start
voice_stt_provider	empty	Home Assistant speech-to-text engine for Voice Input, e.g. stt.faster_whisper. See Voice Input
voice_language	empty	Language for Voice Input, e.g. de (empty uses your browser's language)
statusline	[]	Pieces of the status bar under the prompt, in order (empty is the default, off removes it). See DOCS.md
home_assistant_plugin	true	Install and enable the bundled Home Assistant plugin for Claude. See DOCS.md

auto_launch_claude: true
working_directory: /config
persistent_apk_packages:
  - ripgrep
persistent_pip_packages:
  - httpx
init_commands:
  - nohup /config/scripts/my-bridge.sh > /config/scripts/bridge.log 2>&1 &

Every option is explained in DOCS.md.

Quick start

claude                                 # interactive session
claude "Write an automation that turns on the porch light at sunset"
persist-install ripgrep                # survives restarts
persist-install --python httpx
ha core check                          # or the button in the sidebar

Security

This add-on gives Claude a lot of power by design. It runs as root in its container, can write anywhere in /config, and can call the Supervisor and Home Assistant APIs.

• Any signed-in Home Assistant user can reach it, not only admins. That's how ingress works in HA. Treat every account on your instance as trusted while it's installed.
• Ports 7680 and 7681 are closed by default. Opening one gives anyone on your network a root shell with no login.
• The web UI only accepts Home Assistant's ingress proxy, and ttyd listens only inside the container.
• The sidebar is limited to /config. Your Claude login in /data can't be browsed. Files and Recent are read-only. Changes only writes when you click Revert, Accept or Start tracking, and never pushes.
• dangerously_skip_permissions removes the last human check. A prompt injection in any file or page Claude reads could change your config without asking.

More in DOCS.md → Security.

Architecture support

Architecture	Claude Code	Home Assistant CLI	GitHub CLI
amd64	native, latest	latest	latest
aarch64	native, latest	latest	latest

32-bit ARM (armv7) was dropped in 2.3.9: Home Assistant itself stopped shipping for it after 2025.11. Existing armv7 installs keep the version they have.

The target architecture is resolved from Home Assistant's BUILD_ARCH build argument, so the image builds correctly on each device without relying on BuildKit-specific variables.

Troubleshooting

• Typing lags, then catches up. That comes from Home Assistant's ingress proxy, not the add-on. See DOCS.md.
• Logging in fails. Set auto_launch_claude to false and choose the login helper in the session picker.
• Anything else: check the add-on log and open an issue.

Home Assistant plugin for Claude, included

The add-on ships the homeassistant-config plugin and turns it on at the first start, with no network needed. It teaches Claude current Home Assistant syntax, checks every YAML file Claude writes or edits against the version you run, and adds /ha-check, /ha-upgrade and /ha-find-duplicates. Turn it off with the home_assistant_plugin option or with /plugin inside Claude; updates keep your choice. See DOCS.md.

Community guides

• Running Claude Code inside Home Assistant by Neil Sleightholm: an independent guide to his personal setup, including MCP servers, configuration history and security precautions.

Community tools

• ha-ws-client-go by @schoolboyqueue — lightweight Go CLI for the Home Assistant WebSocket API. Gives Claude direct access to entity states, service calls, automation traces, and real-time monitoring. Single binary, no dependencies.

• claude-statusline by @susomejias — a minimal Claude Code status line with context window, rate limits, git info and session stats. The add-on's Home Assistant status line is based on its style.

Contributors

This add-on keeps getting better thanks to people who send fixes, test releases and write detailed bug reports. Thank you all. 💙

nsleigh

PeterLinuxOSS

mmackenzie2026

miczu71

RobSlabaugh

owine

heytcass

• @nsleigh carried the project through the 2.1.x series: the session picker update option, paste in the terminal, security hardening, offline startup, smaller backups, the login notification, the new launch options and a build that can't hang.
• @PeterLinuxOSS made copying out of the terminal work, with touch-device copy and swipe scrolling.
• @mmackenzie2026 fixed persist-install so packages really persist.
• @miczu71, @RobSlabaugh, @owine and @martinboksa sent earlier fixes and ideas.
• @susomejias designed claude-statusline, the look the Home Assistant status line is based on.
• @heytcass (Tom Cassady) created the original Claude Terminal add-on this project is forked from.

Want to help? PRs are welcome. Smaller, focused ones get reviewed fastest. See the development guide to build and test locally.

License

MIT, the same as the original. See LICENSE.

About the author

Maintained by Javier Santos (@ESJavadex) — AI consultant and founder of Javadex, where I help companies run private AI platforms. I also build Cortex, a self-hosted multi-model AI platform (the same "your AI, your data" philosophy as this add-on). More AI + Home Assistant content (in Spanish) on the Javadex blog.