hom3

k9s-inspired terminal UI for Home Assistant

Navigate your entire Home Assistant setup from the terminal — just like k9s for Kubernetes.

---

Features

• Resource-based navigation — jump to any device type with :lights, :sensors, :climate, etc.
• Live state streaming — subscribes to HA WebSocket, updates in real-time
• Area filtering — filter by area with :lights kitchen or use the area selector in the header
• Fuzzy filter — press / to filter entities by name, entity_id, or state
• Toggle & control — t toggles lights/switches/fans/locks; +/- adjusts brightness, temperature, volume
• Detail panel — attributes, domain-specific controls, and timing for the selected entity
• Multi-home context switching — manage multiple HA instances and switch between them with C or :homes
• Cyberpunk/synthwave theme — cyan, magenta, neon green on dark

---

Quick Start

Install from npm (recommended)

npm install -g @k5s/hom3

Then run:

hom3

Install from source

git clone https://github.com/you/hom3
cd hom3
npm install
npm run build
npm start

Configure

mkdir -p ~/.config/hom3
cat > ~/.config/hom3/config.json << 'EOF'
{
  "homes": [
    {
      "name": "Home",
      "url": "http://homeassistant.local:8123",
      "token": "your_long_lived_access_token"
    }
  ]
}
EOF

Get a token: HA → Profile → Long-Lived Access Tokens

---

Keybindings

Key	Action
↑ / k	Move up
↓ / j	Move down
g / Home	Jump to top
G / End	Jump to bottom
PgUp / PgDn	Page up/down
Enter	Activate selected entity
:	Open command mode
/	Filter (fuzzy search)
t	Toggle selected entity
+ / -	Adjust brightness, temperature, volume, etc.
d	Toggle detail panel
n	Rename selected entity
a	Set area for selected entity
r	Refresh all states
C	Open context switcher (multi-home)
?	Toggle help overlay
q / Ctrl+C	Quit

---

View Commands

Type : then any of the following:

Command	View
:all	All entities
:lights	Lights
:switches	Switches
:sensors	Sensors
:binary_sensors / :bs	Binary sensors
:climate	Climate
:covers	Covers
:fans	Fans
:media / :media_players	Media players
:automations / :auto	Automations
:scripts	Scripts
:scenes	Scenes
:locks	Locks
:cameras	Cameras
:vacuums	Vacuums
:alarms	Alarm panels
:weather	Weather
:buttons	Buttons
:numbers	Number inputs
:selects	Select inputs
:inputs	Input helpers
:homes / :ctx	Context switcher (multi-home)
:quit	Quit

Append an area name to scope a view: :lights kitchen, :sensors bedroom

---

Multi-Home Context Switching

HOM3 supports multiple Home Assistant instances, similar to how k9s handles multiple Kubernetes clusters.

Open the context switcher with C or :homes — the main table switches to a contexts view listing all configured homes. Navigate with j/k, press Enter to connect, Esc to cancel.

The active home name is shown as a badge in the header (top-right of the title bar).

---

Configuration

HOM3 loads config in this order of precedence:

Source	Variables / Flags
CLI flags	--url, --token, --name
Environment variables	HASS_URL, HASS_TOKEN, HASS_NAME
Config file	~/.config/hom3/config.json

Single home

{
  "url": "http://homeassistant.local:8123",
  "token": "your_long_lived_access_token"
}

Multiple homes

{
  "homes": [
    {
      "name": "Home",
      "url": "http://homeassistant.local:8123",
      "token": "your_long_lived_access_token"
    },
    {
      "name": "Cabin",
      "url": "http://192.168.1.100:8123",
      "token": "another_token"
    }
  ]
}

---

Project Structure

src/
├── index.ts        # Entry point, config loading
├── app.ts          # Main app controller, key bindings, event loop
├── hass-client.ts  # Home Assistant WebSocket client
├── renderer.ts     # All rendering logic (rows, detail, bars)
├── widgets.ts      # blessed widget factories
├── theme.ts        # Colors, icons, state formatters
└── types.ts        # TypeScript types