entity-rename

Name: entity-rename
Author: dcb

111stars22forks

How to install entity-rename?

dcb/homeassistant-claude-kit/entity-rename

$npx -y skills add dcb/homeassistant-claude-kit --skill entity-rename

Installs into the current project.

Summary

Batch rename Home Assistant entities to follow a consistent naming convention. Discovers entities, proposes renames, executes via HA API, and updates all YAML/TypeScript references automatically. Trigger phrases: "rename entities", "fix entity names", "standardize entity IDs", "e

Files · 1

View on GitHub

SKILL.md

1	# Entity Rename Skill
2
3	Rename Home Assistant entities to follow a consistent `domain.{room}_{descriptor}`
4	convention. Updates all YAML automations, scripts, dashboard code, and .storage/
5	configs automatically.
6
7	See `references/naming-convention.md` for the full naming convention.
8	See `docs/solutions/tooling/entity-rename-lessons.md` for safety rules from production use.
9
10	## Step 0: Prerequisites
11
12	Verify the environment is ready:
13
14	```bash
15	# Check .env exists with HA connection
16	test -f .env && grep -q HA_TOKEN .env && echo "ENV_OK" \|\| echo "ENV_MISSING"
17
18	# Check entity registry exists (needs make pull first)
19	test -f config/.storage/core.entity_registry && echo "REGISTRY_OK" \|\| echo "REGISTRY_MISSING"
20
21	# Check ha-ws is available on HA instance
22	source .env 2>/dev/null
23	ssh "$SSH_USER@$HA_HOST" "command -v ha-ws" >/dev/null 2>&1 && echo "HAWS_OK" \|\| echo "HAWS_MISSING"
24	```
25
26	- `ENV_MISSING`: Tell user to run `setup-infrastructure` first or create `.env` manually.
27	- `REGISTRY_MISSING`: Tell user to run `make pull` first.
28	- `HAWS_MISSING`: Install claude-code-ha on the HA instance:
29	```bash
30	ssh "$SSH_USER@$HA_HOST" "bash ${HA_REMOTE_PATH}claude-code-ha/install.sh"
31	```
32	See [danbuhler/claude-code-ha](https://github.com/danbuhler/claude-code-ha). Provides `ha-api` (REST) and `ha-ws` (WebSocket) CLI tools that run directly on HA.
33
34	## Step 1: Discovery
35
36	Parse local registry files to build a complete entity inventory:
37
38	```bash
39	source venv/bin/activate
40	python tools/entity_explorer.py config/ --full
41	```
42
43	This uses the device registry join (entity.device_id -> device.area_id) to resolve
44	areas for entities that don't have a direct area_id.
45
46	Present the inventory to the user grouped by area/room:
47	- Show entity count per area
48	- Highlight entities that don't follow the naming convention
49	- Flag entities with serial numbers, product names, or non-English names
50
51	## Step 2: Convention Proposal
52
53	For each non-conforming entity, propose a new name following `references/naming-convention.md`.
54
55	Present renames grouped by room. For each room, show:
56
57	```
58	Living Room (12 entities to rename):
59	climate.jch_8862dcd1 -> climate.living_room_ac
60	light.hue_ambiance_spot_1 -> light.living_room_spot_1
61	...
62	[Approve all] [Edit] [Skip room]
63	```
64
65	Before proposing each rename:
66	1. Verify target entity_id doesn't already exist (safety rule 3)
67	2. Detect name collisions requiring two-step renames (safety rule 4)
68	3. For each device, enumerate ALL child entities (safety rule 2):
69	- battery, calibration, heating, window_detection, anti_scaling, etc.
70	- Use device_id from entity registry to find siblings
71
72	Save approved renames to a JSON file for batch execution:
73
74	```bash
75	# Write to entity-renames.json (or a temp batch file)
76	python3 -c "
77	import json
78	renames = [
79	{'old_id': 'climate.jch_8862dcd1', 'new_id': 'climate.living_room_ac'},
80	...
81	]
82	with open('rename_batch.json', 'w') as f:
83	json.dump(renames, f, indent=2)
84	"
85	```
86
87	## Step 3: Reference Scanning
88
89	Before executing, scan for all references to understand the blast radius:
90
91	```bash
92	source venv/bin/activate
93	python tools/update_yaml_refs.py rename_batch.json --dry-run
94	```
95
96	This shows which files reference each old entity ID and how many replacements
97	would be made. Present the summary to the user:
98
99	```
100	climate.jch_8862dcd1: 34 references across 5 files
101	config/automations/climate.yaml: 18 refs
102	config/scripts/climate.yaml: 8 refs
103	config/configuration.yaml: 4 refs
104	dashboard/src/lib/entities.ts: 2 refs
105	config/automations.yaml: 2 refs
106	```
107
108	## Step 4: Batch Execution
109
110	Execute renames in batches, grouped by room. For EACH batch:
111
112	### 4a. Rename entities on HA
113
114	Primary (ha-ws via SSH):
115	```bash
116	# Rename a single entity
117	ssh "$SSH_USER@$HA_HOST" "source /etc/profile.d/claude-ha.sh; source ${HA_REMOTE_PATH:=/config/}.env; ha-ws entity update sensor.old_name new_entity_id=sensor.new_name"
118
119	# Batch rename from a file
120	cat rename_batch.json \| python3 -c "
121	import json, sys, subprocess
122	for r in json.load(sys.stdin):
123	cmd = f'ha-ws entity update {r[\"old_id\"]} new_entity_id={r[\"new_id\"]}'
124	print(f'Renaming: {r[\"old_id\"]} -> {r[\"new_id\"]}')
125	subprocess.run(['ssh', '$HA_HOST', f'source /etc/profile.d/claude-ha.sh; source ${HA_REMOTE_PATH:=/config/}.env; {cmd}'])
126	"
127	```
128
129	Alternative (Python script with WebSocket fallback):
130	```bash
131	source venv/bin/activate
132	python tools/entity_rename.py rename_batch.json
133	```
134	Only needed if SSH is unavailable. The script connects directly via WebSocket.
135
136	### 4b. Update all YAML/TypeScript references locally
137
138	```bash
139	python tools/update_yaml_refs.py rename_batch.js

People who liked this also viewed

6 picks

Type

entity-rename

111stars22forks

View on GitHub

How to install entity-rename?

dcb/homeassistant-claude-kit/entity-rename

$npx -y skills add dcb/homeassistant-claude-kit --skill entity-rename

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Entity Rename Skill
2
3	Rename Home Assistant entities to follow a consistent `domain.{room}_{descriptor}`
4	convention. Updates all YAML automations, scripts, dashboard code, and .storage/
5	configs automatically.
6
7	See `references/naming-convention.md` for the full naming convention.
8	See `docs/solutions/tooling/entity-rename-lessons.md` for safety rules from production use.
9
10	## Step 0: Prerequisites
11
12	Verify the environment is ready:
13
14	```bash
15	# Check .env exists with HA connection
16	test -f .env && grep -q HA_TOKEN .env && echo "ENV_OK" \|\| echo "ENV_MISSING"
17
18	# Check entity registry exists (needs make pull first)
19	test -f config/.storage/core.entity_registry && echo "REGISTRY_OK" \|\| echo "REGISTRY_MISSING"
20
21	# Check ha-ws is available on HA instance
22	source .env 2>/dev/null
23	ssh "$SSH_USER@$HA_HOST" "command -v ha-ws" >/dev/null 2>&1 && echo "HAWS_OK" \|\| echo "HAWS_MISSING"
24	```
25
26	- `ENV_MISSING`: Tell user to run `setup-infrastructure` first or create `.env` manually.
27	- `REGISTRY_MISSING`: Tell user to run `make pull` first.
28	- `HAWS_MISSING`: Install claude-code-ha on the HA instance:
29	```bash
30	ssh "$SSH_USER@$HA_HOST" "bash ${HA_REMOTE_PATH}claude-code-ha/install.sh"
31	```
32	See [danbuhler/claude-code-ha](https://github.com/danbuhler/claude-code-ha). Provides `ha-api` (REST) and `ha-ws` (WebSocket) CLI tools that run directly on HA.
33
34	## Step 1: Discovery
35
36	Parse local registry files to build a complete entity inventory:
37
38	```bash
39	source venv/bin/activate
40	python tools/entity_explorer.py config/ --full
41	```
42
43	This uses the device registry join (entity.device_id -> device.area_id) to resolve
44	areas for entities that don't have a direct area_id.
45
46	Present the inventory to the user grouped by area/room:
47	- Show entity count per area
48	- Highlight entities that don't follow the naming convention
49	- Flag entities with serial numbers, product names, or non-English names
50
51	## Step 2: Convention Proposal
52
53	For each non-conforming entity, propose a new name following `references/naming-convention.md`.
54
55	Present renames grouped by room. For each room, show:
56
57	```
58	Living Room (12 entities to rename):
59	climate.jch_8862dcd1 -> climate.living_room_ac
60	light.hue_ambiance_spot_1 -> light.living_room_spot_1
61	...
62	[Approve all] [Edit] [Skip room]
63	```
64
65	Before proposing each rename:
66	1. Verify target entity_id doesn't already exist (safety rule 3)
67	2. Detect name collisions requiring two-step renames (safety rule 4)
68	3. For each device, enumerate ALL child entities (safety rule 2):
69	- battery, calibration, heating, window_detection, anti_scaling, etc.
70	- Use device_id from entity registry to find siblings
71
72	Save approved renames to a JSON file for batch execution:
73
74	```bash
75	# Write to entity-renames.json (or a temp batch file)
76	python3 -c "
77	import json
78	renames = [
79	{'old_id': 'climate.jch_8862dcd1', 'new_id': 'climate.living_room_ac'},
80	...
81	]
82	with open('rename_batch.json', 'w') as f:
83	json.dump(renames, f, indent=2)
84	"
85	```
86
87	## Step 3: Reference Scanning
88
89	Before executing, scan for all references to understand the blast radius:
90
91	```bash
92	source venv/bin/activate
93	python tools/update_yaml_refs.py rename_batch.json --dry-run
94	```
95
96	This shows which files reference each old entity ID and how many replacements
97	would be made. Present the summary to the user:
98
99	```
100	climate.jch_8862dcd1: 34 references across 5 files
101	config/automations/climate.yaml: 18 refs
102	config/scripts/climate.yaml: 8 refs
103	config/configuration.yaml: 4 refs
104	dashboard/src/lib/entities.ts: 2 refs
105	config/automations.yaml: 2 refs
106	```
107
108	## Step 4: Batch Execution
109
110	Execute renames in batches, grouped by room. For EACH batch:
111
112	### 4a. Rename entities on HA
113
114	Primary (ha-ws via SSH):
115	```bash
116	# Rename a single entity
117	ssh "$SSH_USER@$HA_HOST" "source /etc/profile.d/claude-ha.sh; source ${HA_REMOTE_PATH:=/config/}.env; ha-ws entity update sensor.old_name new_entity_id=sensor.new_name"
118
119	# Batch rename from a file
120	cat rename_batch.json \| python3 -c "
121	import json, sys, subprocess
122	for r in json.load(sys.stdin):
123	cmd = f'ha-ws entity update {r[\"old_id\"]} new_entity_id={r[\"new_id\"]}'
124	print(f'Renaming: {r[\"old_id\"]} -> {r[\"new_id\"]}')
125	subprocess.run(['ssh', '$HA_HOST', f'source /etc/profile.d/claude-ha.sh; source ${HA_REMOTE_PATH:=/config/}.env; {cmd}'])
126	"
127	```
128
129	Alternative (Python script with WebSocket fallback):
130	```bash
131	source venv/bin/activate
132	python tools/entity_rename.py rename_batch.json
133	```
134	Only needed if SSH is unavailable. The script connects directly via WebSocket.
135
136	### 4b. Update all YAML/TypeScript references locally
137
138	```bash
139	python tools/update_yaml_refs.py rename_batch.js

People who liked this also viewed

6 picks

Type