Windows Toast Notify for Hermes CLI

Fire a Windows toast notification when Hermes CLI needs user input —
either a clarify question or a dangerous-command approval — so the user
doesn't have to watch the terminal.

CLI mode has zero built-in notification capability (unlike the Desktop app).
This skill bridges that gap using winotify (Python) + shell hooks.

When to Load

• User wants toast notifications when Hermes asks a question or needs approval
• User wants to verify existing toast setup is working
• Toasts stopped appearing and need debugging

Architecture

Three layers, bundled in this skill:

hermes-hook-notify.py   ← hook bridge: reads stdin JSON from Hermes, dispatches
  ↓ calls (same directory)
hermes-notify.py        ← toast emitter: winotify → Windows toast
  ↓ registered in
config.yaml             ← hooks: pre_tool_call(clarify) + pre_approval_request

Setup (one command)

python scripts/setup.py

Then restart the session (/reset or relaunch Hermes). The setup script:

1. Discovers the Hermes venv Python via %LOCALAPPDATA%\hermes\hermes-agent\venv
2. Installs winotify into that venv (skips if already present)
3. Reads config.yaml (found via hermes config path)
4. Writes hook entries for pre_approval_request and pre_tool_call (matcher: clarify)
5. Prints the exact paths used so the user can verify

After setup, fully quit and relaunch Hermes. Shell hooks are loaded at
startup; mid-session changes have no effect. /reset only resets the
conversation — it does NOT re-register hooks. Close the terminal window
(or Ctrl+C) and start Hermes again.

Verification

After restarting, verify the pipeline end-to-end:

1. Toast emitter (bottom layer)

"<venv-python>" "<skill-dir>/scripts/hermes-notify.py" "测试" "toast 发射器直测"

Should see "toast sent" and a toast popup.

2. Hook bridge (manual payload)

echo '{"hook_event_name":"pre_tool_call","tool_name":"clarify","tool_input":{"question":"测试 clarify toast"}}' | python "<skill-dir>/scripts/hermes-hook-notify.py"
echo '{"hook_event_name":"pre_approval_request","command":"rm -rf /tmp/test"}' | python "<skill-dir>/scripts/hermes-hook-notify.py"

Both should pop a toast. Hook script outputs {}.

3. Live clarify (full pipeline)

Ask the agent to call clarify. A toast should appear before the question prompt.

4. Live approval (full pipeline)

Run a dangerous command (e.g. rm -rf /tmp/test). A toast should appear before the approval prompt.

Design Principles

1. No hardcoded user paths. Scripts discover venv Python via %LOCALAPPDATA% and resolve sibling scripts via __file__. The only path the user touches is running setup.py.
2. Scripts bundled in skill. No manual file creation. setup.py handles registration.
3. duration=long (25s) — default "short" (5s) is too easy to miss.
4. Audio cue — plays Windows Default notification sound so the user is alerted even when not looking at the screen.
5. Timestamp suffix — each toast body ends with (HH:MM:SS) to bypass Windows same-AppId toast suppression (consecutive toasts from the same AppId within ~30-60s are silently dropped).
6. subprocess.run (blocking), not Popen — ensures the toast subprocess finishes before the hook returns. Popen's child can be orphaned when the parent's subprocess.run(capture_output=True) captures the hook's stdout and moves on.
7. stdout → DEVNULL — hook runs silently, doesn't pollute agent output. Switch to PIPE when debugging.

Pitfalls

winotify

• AUMID trap. Raw PowerShell WinRT ToastNotificationManager.Show() returns success but Windows silently drops the toast if no AppUserModelID is registered. winotify handles AUMID registration automatically (creates a Start Menu shortcut on first run). This is why winotify was chosen over raw PowerShell.
• Must install into Hermes venv, not system pip. The venv Python is the one that runs hook scripts. setup.py handles this automatically.

Hook bridge

• Do NOT use sys.executable. Shell hooks are spawned via subprocess.run(argv, shell=False). The python on PATH may resolve to a uv-managed Python without winotify, not the Hermes venv Python. The hook script must discover the venv Python via %LOCALAPPDATA%. setup.py hardcodes the discovered path into the hook script at setup time so the hook doesn't need to search at runtime.
• pre_approval_request payload fields are in extra, not top-level. shell_hooks._serialize_payload() puts non-standard kwargs (command, description, pattern_key, etc.) into payload["extra"]. Check both payload.get("command") and payload.get("extra", {}).get("command").
• subprocess.DEVNULL hides errors. When debugging, temporarily replace stdout=DEVNULL, stderr=DEVNULL with stdout=PIPE, stderr=PIPE + proc.communicate() to capture actual errors.

Hooks registration

• hermes config set cannot write list-valued hooks. Setting hooks.pre_tool_call to a JSON array produces a quoted YAML string that the hooks parser silently ignores. Always manually edit the YAML file. setup.py does this.
• Hooks need /reset to take effect. Shell hooks are registered at startup.
• hermes hooks list may report "No shell hooks" on Windows. It reads from ~/.hermes/config.yaml by default, but the actual config may be at %LOCALAPPDATA%\hermes\config.yaml. Check with hermes config path.

Windows toast behavior

• Same-AppId toast suppression. Windows silently drops consecutive toasts from the same AppId within ~30-60s. The timestamp suffix in hermes-notify.py bypasses this.
• Windows notifications must be enabled. Settings → System → Notifications → "Get notifications from apps and other senders" must be ON.
• Focus Assist / Do Not Disturb will suppress toasts. Check Windows settings.
• Session-approved patterns skip the hook. When the user chooses "session" or "always" for a dangerous command, is_approved() short-circuits and pre_approval_request does not fire. Only "allow once" re-fires the hook every time. This is by design — the hook observes the prompt, not every execution.

Debugging

If toasts don't appear, debug in this order:

1. Is winotify installed in the venv? Run <venv-python> -c "import winotify; print('ok')".
2. Does the emitter work? Run hermes-notify.py directly with test args.
3. Does the hook bridge work? Pipe JSON payload manually (see Verification step 2).
4. Are hooks registered? Check config.yaml has the hooks: block with correct paths.
5. Is the hook actually firing? Add file-based logging to hermes-hook-notify.py (append timestamped lines to a log file), because hook stdout/stderr are captured by shell_hooks._spawn() and not shown to the user.