Turn your Windows HTPC into a locally-paired Google Home device. Say "Hey Google, set HTPC volume to 40 %", tap tiles in the Home app, or wire routines ("movie time") — MatterHelm executes the media, volume, power, and custom actions directly on the PC.
No cloud, no OAuth server, no paid certification: pairing is a one-time QR-code scan — Matter over your local network via a matter.js virtual bridge, executed natively by a small Windows tray app. Fully self-contained by ADR-001: no external services and no companion apps.
Google Home app / Nest speaker
│ Matter (local network)
▼
bridge/ Node 22 + matter.js sidecar (Matter Aggregator: Speaker + switches)
│ localhost WebSocket, token-auth
▼
app/ C# .NET 10 WinForms tray app (lifecycle + dispatch + UI)
├─ BridgeLifecycleCoordinator / BridgeActionDispatcher / VolumeStatePublisher
├─ ActionExecutor → focused media router / CoreAudio / key chords / system commands
└─ Overlay HUD → click-through pop-ups: incoming command + result
- Voice + app + routines — volume/mute with a real slider; retained Play/Pause, Next, and Previous switches; and configurable Power behavior: displays off/on, pause then displays off/on (without resuming playback), screensaver start/stop, or momentary sleep.
- Custom commands — each becomes its own retained Google Home switch by default, with an opt-in Reset after activation one-shot mode: press a media key, launch a program, send a keyboard chord (typed or captured), run a system command (screensaver, lock, sleep, hibernate, shutdown…), or chain them into a macro with waits.
- Robust command handling — actions dispatch from Matter commands, so repeated voice commands and every tile tap fire (no dropped taps); long macros never block other commands.
- Overlay HUD — click-through, non-activating pop-ups for each command with a volume fill bar; 8 screen positions, light/dark/system theme, adjustable opacity.
- Settings UI — categorized pages with search, staged edits, inline validation, live preview.
- Local-first diagnostics — structured logs, metrics snapshots with resource gauges, one-click privacy-scrubbed diagnostics export. Nothing ever leaves the machine.
- Lean — budgets: tray ≤ 32 MB private, sidecar ≤ 120 MB (one process), idle CPU < 0.5 %, measured per release (ADR-007); latest measurement 2026-09-10: tray 18.5 MB, sidecar 90.8 MB, idle 0.0 % / 0.1 %.
Start to finish this takes about 15 minutes, most of it the one-time Google registration. The user guide covers every step in more detail plus troubleshooting.
| Need | Why |
|---|---|
| Windows 10 version 1809 (build 17763) or later, x64 | The current app target is net10.0-windows10.0.17763.0; Windows 10 and 11 are supported |
| A Google Nest hub on the same LAN — Nest Hub/Mini/Audio, Nest Wifi Pro, or Google TV Streamer | Google requires a hub to commission Matter devices; a phone alone cannot (docs/adr/002) |
| IPv6 enabled on the active network adapter | A hard Matter requirement, even though all traffic stays local. It's on by default — only check this if pairing later fails |
| The Google Home app, signed into the account that manages your home | Does the pairing scan |
MatterHelm isn't a commercially certified Matter product, so Google will only pair it if your own account has registered its identifiers first. Free, no review, ~5 minutes, once per Google account.
- Go to console.home.google.com and sign in with the same account your Home app uses.
- Create a project (any name).
- Add integration → Matter.
- Enter the sanctioned test IDs: VID
0xFFF1, PID0x8000. Pick the bridge/aggregator device type if offered — Google gates pairing on the VID/PID, not that field. Leave it as a development/test integration; don't submit for certification. - Save as a draft integration.
Google's console UI moves around. If wording doesn't match, look for "test device", "unlisted", or "development".
Download from Releases:
- Installer —
MatterHelm-Setup-<version>.exe: per-user install (no admin prompt), Start-menu entry, optional start-with-Windows, clean uninstall that keeps your pairing and settings. - Portable —
matterhelm-v<version>-win-x64.zip: unzip anywhere and runMatterHelm.exe.
Either way it's self-contained — the Matter sidecar ships as a bundled single
exe, so no Node.js or .NET runtime is required. Optionally verify the
download against the release's SHA256SUMS.txt:
certutil -hashfile MatterHelm-Setup-<version>.exe SHA256
Unsigned binaries: SmartScreen may warn on first run — "More info" → "Run anyway". Code-signing is on the roadmap.
Run it: a helm icon appears in the system tray (check the hidden-icons area). That's the entire UI. On a fresh install a setup guide opens with the remaining steps and a button that does them for you — steps 4 and 5 below are the same thing done by hand. (Tray menu → Setup guide… reopens it.)
Right-click the tray icon → Settings… → Devices. The names here become your voice targets and are what the Home app offers during pairing, so set them now — especially if more than one PC will run MatterHelm (see below). Untick anything you don't want published.
- Right-click the tray icon → Pair with Google Home…. On an unpaired install this is the bridge-start action: it enables and persists the bridge and opens the pairing window. Enable bridge is intentionally hidden until pairing has completed.
- The icon is briefly amber while starting, then blue when the bridge is healthy, advertising, and awaiting pairing. Allow the Windows Firewall prompt for Private networks. Without it the hub can't discover the bridge.
- The pairing window shows the phone-side steps, a QR code, an 11-digit manual code, and a live status line that follows the bridge through to paired.
- In the Home app: + → Add device → Matter-enabled device, scan the QR (or "Set up without QR code" and type the manual code).
- Tap through the "not Matter-certified" notice — expected for a self-hosted device. A hard "Not a Matter-certified device" failure instead means step 2 didn't take.
- Pick a home/room and confirm the device names. The tray icon turns green.
Tray legend: monochrome (theme-matched) = disabled; amber = starting or awaiting lifecycle status; blue = healthy and awaiting pairing; green = commissioned and connected; red = a sidecar crash loop or missing commissionable advertisement.
You'll get tiles for HTPC Speaker, HTPC Play Pause, HTPC Next, HTPC Previous, HTPC Power, plus one per custom command.
"Hey Google, set HTPC Speaker volume to 40 %" "Hey Google, turn on HTPC Play Pause"
Play/Pause sends the requested Play or Pause command to the focused program first. It uses an absolute Windows media-session fallback only when the session belongs to the same app; sessionless players such as Kodi can receive the focused command, but MatterHelm cannot verify the result.
Next and Previous retain their displayed state and fire once on either user transition.
For natural phrasing like "pause the HTPC", set up Google Home routines — see docs/routines.md.
Each PC pairs separately and appears as its own set of devices. You need no second Google account, second Console project, second hub, or different Vendor/Product IDs — every install mints its own Matter identity on first run, which is what keeps them distinct.
The one thing that needs your attention is names, since every install ships the same defaults and duplicate names make voice commands ambiguous.
On the second (third, …) PC:
- Install and run it. A fresh unpaired install remains disabled until you choose Pair with Google Home….
- Settings → Devices → set Bridge name (e.g. "Office Bridge" — what Google calls the bridge itself) and rename each device: "Office Speaker", "Office Play Pause", "Office Power", … Save.
- (Optional check) Settings → Advanced → Device identity seed should differ from the other PC's.
- Choose Pair with Google Home… and allow the firewall prompt — it's a fresh prompt on this PC.
- Complete pairing as in step 5 above, using the same Google account and home. Put it in a different room if you can; it makes voice targeting easier.
Then both respond independently: "pause the office PC" vs "pause the HTPC".
Cloned machines: if the second PC was made by imaging the first (or you
copied %APPDATA%\MatterHelm\config.json across), it inherits the first
PC's identity and the two will conflict. Fix: close MatterHelm on the clone,
delete the "uniqueIdSeed" line from config.json and the matter folder
beside it, then start it — a fresh identity is minted.
| Doc | What's in it |
|---|---|
| User guide | The setup above in more depth, plus the full settings tour, custom commands and macros, troubleshooting, and privacy |
| Natural voice phrases | Routine starters and retained/resettable switch guidance |
| Architecture blueprint | Binding design & IPC protocol spec |
| ADRs | Every architectural decision, with context and consequences |
| Engineering standards | The quality bar (TS + C#) |
| Research | Why this integration route (July 2026 survey) |
Push-Location bridge
npm ci
npm run verify # sidecar: lint + types + tests
Pop-Location
dotnet test app/MatterHelm.Tests/MatterHelm.Tests.csproj -c Release # all discovered tests
.\build.ps1 # dist/: portable folder, SEA sidecarDev requirements: Node 22.13+ LTS, .NET 10 SDK, Windows. CI runs the same gates on every push (bridge verify on Ubuntu and Windows, bridge coverage on Ubuntu, and app build + tests + coverage on Windows).
MatterHelm is developed with AI coding agents under human review, using the
transparent workflow in CLAUDE.md. Every change is held to the
same review, test, coverage, and documentation gates regardless of who or what
wrote it.
The current release is v0.7.1 (2026-09-01). MatterHelm has been commissioned and exercised on real Google Nest hardware; known limits are unsigned binaries that may trigger SmartScreen, the one-time Google test-VID registration, and unverifiable delivery to sessionless players such as Kodi.
Current automated gates and coverage are published by
CI; per-release
results belong in the corresponding release notes. See
CHANGELOG.md for release history.
The maintained work index and proposed queue are in BACKLOG.md.
Issues and PRs welcome — see CONTRIBUTING.md for the
build/test workflow, engineering bar, commit conventions, and the
protocol-parity and ADR rules that govern changes. Questions →
SUPPORT.md.
Report suspected vulnerabilities privately per SECURITY.md
(GitHub Security Advisories), not in a public issue.
MIT — see LICENSE. "Matter" and the Matter certification mark
are trademarks of the Connectivity Standards Alliance (CSA); see
NOTICE. MatterHelm is an independent project, not affiliated
with or endorsed by the CSA or Google.