CrappyClaude

Claude Code in a terminal in your Home Assistant sidebar.

---

Requirements

Claude Code is a native binary that needs the AVX CPU instruction set. Virtual machines with a generic CPU type (Proxmox kvm64, x86-64-v2-AES, QEMU qemu64) hide AVX, and the install fails there.

On Proxmox, set the Home Assistant VM's CPU type to host. If host is not in the GUI dropdown, run this in the node's Shell (replace 100 with your VM ID):

qm set 100 --cpu host

Then Shutdown the VM and Start it again. A reboot from inside Home Assistant does not apply the change.

Features

Feature	What it does
Claude Code	The current Claude Code CLI in a web terminal in the HA sidebar. Starts automatically, works in your HA config folder, and stays logged in across restarts.
CLAUDE.md agent config	An editable agent config file Claude reads every session, with a Home Assistant-focused default.
ha command	Lets Claude validate your config (ha core check) and read Home Assistant logs.

Installation

1. In Home Assistant, go to Settings > Apps > App Store.
2. Open the menu (three dots, top right) > Repositories.
3. Add https://forgejo.dom.network/domuk/HA-Addon-CrappyClaude and close.
4. Find CrappyClaude in the store and click Install. It builds on your machine, which takes a few minutes.
5. Click Start, then open CrappyClaude in the sidebar.
6. Claude starts by itself. The first time, log in with your Claude account.

Settings

Setting	Type	Default	What it does
Start Claude automatically	On/off	On	Start Claude as soon as the panel opens. Off gives a plain terminal.
Resume last chat	On/off	On	Open the panel in your last chat. Starts a new one if there is none. /resume in Claude picks an older chat.
Full screen mode	On/off	On	Claude Code's full screen view, without flicker. Scroll with Page Up / Page Down.
Font size	10-24	14	Terminal text size.
Terminal theme	dark / light	dark	Terminal colours.
Working directory	Text	/homeassistant	The folder Claude starts in. /homeassistant is your HA config.
CLAUDE.md file	Text	CLAUDE.md	Which agent config file Claude reads from the app's folder.
Copy with the browser	On/off	On	Leaves text selection to the browser, so copying works in the panel. Off lets Claude use the mouse instead, but copying then does not work.
Home Assistant MCP URL	URL	empty	Your Home Assistant MCP server's full URL. Claude Code connects to it as homeassistant.

Home Assistant MCP

The app does not include an MCP server, but it can connect Claude Code to one you run, such as the Home Assistant MCP Server app.

1. Copy the server's URL from its log. It looks like http://<home-assistant-ip>:9583/private_xxxx. The secret path at the end is required.
2. Replace <home-assistant-ip> with your Home Assistant's IP address.
3. Paste the URL into Home Assistant MCP URL in this app's settings, save, and restart the app.

Claude Code then has the server as homeassistant. Check it with /mcp in Claude, or claude mcp list in the terminal.

• If the MCP server's URL changes, paste the new one and restart.
• Clearing the setting removes the server on the next restart. Servers you added yourself with claude mcp add are never touched.
• The URL is a secret, so the app's log only shows its address and port.
• Versions before 3.0.0 included a third-party server (hass-mcp). 3.0.0 removes it.

CLAUDE.md (agent config)

CLAUDE.md tells Claude how to behave: where your config lives, how to work safely, and useful Home Assistant commands.

• Where it lives: the app's own folder, app_configs/<id>_crappyclaude/CLAUDE.md. File editor may show it under /addon_configs/.
• First start: the app writes a default CLAUDE.md there. After that it is never overwritten, so your edits are kept.
• Your own versions: put other .md files in the same folder and set CLAUDE.md file to their name. If the file is missing, the app falls back to CLAUDE.md.
• When changes apply: every time you open the panel.

The default makes Claude read before changing anything, explain each edit first, never touch .storage, keep secrets in secrets.yaml, run ha core check after edits, and never restart Home Assistant without your OK.

Folders Claude can access

Path in the app	What it is	Access
/homeassistant	Your Home Assistant config	Read and write
/share	HA share folder	Read and write
/media	HA media folder	Read and write
/config	This app's own folder (holds CLAUDE.md)	Read and write

Permissions and safety

• Nothing is pre-approved. Claude asks before every file edit, command or MCP action.
• You can choose "allow" options inside Claude Code when it asks. The app never overrides this.
• Claude Code's self-updater is turned off. Each app update installs the Claude Code release current at that time.
• Take a backup (Settings > System > Backups) before letting Claude make big changes.

Limitations

• Needs a CPU with AVX (see Requirements). There is no build of current Claude Code that works without it.
• Claude Code is the release that was current when the app was installed or last updated. To get a newer one, update or rebuild the app.
• amd64 only.
• The terminal session ends when you close the panel. Claude's login and settings are kept.

Troubleshooting

Problem	What to check
Install fails	Settings > System > Logs, choose Supervisor, and look for the build error. A failure at claude --version usually means the CPU has no AVX (see Requirements).
App does not start	The app's Log tab.
CLAUDE.md changes not used	Close and reopen the panel. Check the CLAUDE.md file setting matches the file name.
Copying does nothing (Claude shows it copied)	Turn on Copy with the browser and restart the app. Then select text and use right-click Copy or Ctrl+C.
MCP tools missing	Check Home Assistant MCP URL is the full URL including the secret path, restart the app, then run /mcp in Claude to see whether it connected.
Version still shows old after an update	App Store > three dots > Check for updates.

Credits and references

CrappyClaude is written from scratch. These projects and threads informed it:

• robsonfelix-hass-addons: Claude Code app for HA. Base image choice, ttyd setup, and the idea of an HA-focused CLAUDE.md.
• heytcass/home-assistant-addons: the original Claude Terminal app for HA.
• jantimon/ha-addon-ssh: the idea of a configurable CLAUDE.md.
• HA Community thread: Claude Code slim fork: reports of the no-AVX problem on Proxmox VMs.
• anthropics/claude-code#19981: Claude Code crashing on VMs without AVX.
• ttyd: the web terminal.
• Home Assistant CLI: the ha command.
• Claude Code: Anthropic's Claude Code CLI.
• Home Assistant app developer docs