Home Assistant : a Native macOS Tray App

Background

Since February 2025, this blog has been very quiet. I had health issues, and I did not give this space the time it deserved. Now I am giving myself a challenge: bring it back to life with practical projects.

At the same time, I moved from Domoticz to Home Assistant.  Domoticz served me well for more than 10 years on a Raspberry Pi 3, but I felt I had reached its limits for my needs. I wanted more flexibility and a cleaner path forward. After switching to Home Assistant, one problem remained: I wanted a way to see critical values instantly, without opening my phone or the full HA web interface. That requirement became a project.

The idea

Build a native macOS app that lives in the menu bar, near the clock.

- One click: show selected entities;

- Mouse hover: quick values directly from the tray icon;

- Once click on a spécific sensor : go the the HA web UI and show today graph.

Simple, fast, always available.

I called it HAStatusTray.

Building HAStatusTray

I started with a minimal version:

1. Connect to Home Assistant with URL + long-lived token;
2. Fetch entities from `GET /api/states`;
3. Keep relevant domains (`sensor.*`, `binary_sensor.*`);
4. Display selected values in a compact popover.

That first build already solved the core problem.

Then I had many ideas coming in and decided to enhance the product to make it the product of my dreams.

Current feature set

Connection and setup

• Dedicated Connection tab;
• URL + token validation with Test connection;
• Optional Ignore SSL certificate errors mode for local/self-signed setups;
• Configurable auto-refresh interval (minimum 20 seconds);
• Launch app at login option.

Entity management

• Supports "sensor.*", "binary_sensor.*", and "switch.*" (read-only monitoring);
• Sensors tab with discovery + real-time quick search;
• Show selected filter;
• Bulk actions: "Select all", "Clear", "Refresh";
• Local friendly names (app-only, no rename in Home Assistant).

Main tray window

• Clickable Home Assistant title opens instance URL in browser;
• Version/build shown under title;
• Selected entities and values in a compact list;
• Re-Order mode with drag and drop;
• Remove an entity directly while reordering;
• Last refresh shown with seconds.

Tray interactions

• Left click : open/close popover;
• Right click : context menu (`Settings`, `View logs`, `Quit`);
• Mouse hover : multiline tooltip with key values.

Runtime logs

•  Dedicated **Logs** window from tray menu;
•  Timestamped runtime lines (connect, fetch, refresh, errors, UI actions);
•  Filter levels: "All", "Info", "Warn", "Error";
• "`Real-time" and "Freeze" modes.
•  "ERROR" lines in red, "WARN" lines in orange.
•  Sensor/value retrieval lines highlighted for readability.

Security and persistence choices

Two decisions were non-negotiable:

1. Token in macOS Keychain, never in plain config files;
2. XML config file for non-secret data:

• Home Assistant URL;
• selected entities and order;
• local friendly names;
• refresh interval;
• SSL-ignore toggle.

Logs are also persisted to disk with auto-flush when the log file exceeds 5 MB.

Reliability improvements

A major practical improvement was clearer error categories:

• Authentication error (invalid/rejected token),
• Network connection error (offline/unreachable host),
• TLS error (certificate/HTTPS handshake), plus protocol/server/configuration errors.

That made troubleshooting much faster during day-to-day use.

What I learned

This project was a strong way to learn native macOS development with SwiftUI + AppKit together.

I learned how to:

• design for very fast interactions;
• handle secure credential storage correctly;
• keep state consistent across floating panels and tray UI;
• build observability into a local desktop app;
• iterate based on real usage.

Most importantly, shipping something useful to myself was the best way to stay focused.

What's next

Planned improvements:

• installable package workflow;
• cleaner release/update pipeline;
• richer per-entity display options;
• optional alerts for critical values.

For now, HAStatusTray already does exactly what I wanted :

Instant Home Assistant visibility from the macOS menu bar

How can I get it ?

Easy, the entire project : binary + source code is available on my GitHub, feel free to get the .IMG and have a look at the code too. It's all yours.

Screenshots

Main window

Re-organise mode

Connection settings

Sensors settings

Log screen

Right click on App icon

I hope this helps ;)