Metadata-Version: 2.4
Name: hermes-notify
Version: 0.3.1
Summary: A config-driven notification router — rule matching, audio playback, multi-backend command execution
Author-email: LinQuan <i@linquan.name>
License: MIT
Project-URL: homepage, https://github.com/mlinquan/hermes-notify
Project-URL: repository, https://github.com/mlinquan/hermes-notify
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# hermes-notify

[English](./README.md) | [中文](./README.zh.md)

A config-driven notification router for Hermes Agent — rule matching, context injection, audio playback, and custom command execution.

Transport-agnostic. Reads messages from stdin or a Bus hook, matches against `notify.yaml` rules, and executes the configured action.

## What is this?

hermes-notify is a **message router** for the Hermes Agent ecosystem. When a message arrives (from a bus, a script, or stdin), it checks the message type against your `notify.yaml` rules. If a rule matches, it executes the configured command — anything from a macOS notification to a Slack webhook.

### Quickstart

1. Install: `pip install hermes-notify`
2. Create a `notify.yaml` config file with a rule (see Configuration below)
3. Send a message: `notify-hermes --to my-service --type task_done "Hello"`
4. The callback matches `match_type: task_done` and runs your command

## Install

```bash
pip install hermes-notify
```

Or from source:

```bash
git clone https://github.com/mlinquan/hermes-notify.git
cd hermes-notify && pip install -e .
```

## CLI

```bash
# Send a message to any bus endpoint
notify-hermes --to my-service --type task_done "Task completed"
notify-hermes --to my-service --type progress "50% done"
notify-hermes --to my-service --type ack "Received"

# Send a notification to a tmux session
notify-agent mysession "Start working"
notify-agent --simple mysession "FYI: something happened"

# Process a callback message from stdin
echo '{"body":{"type":"task_done","text":"done"}}' | hermes-callback
```

## Configuration

Route rules are defined in `~/.hermes/bus-rules.yaml` and processed by
[hermes-bus-plugin](https://github.com/mlinquan/hermes-bus-plugin).
See its README for the full rule format.

This section only covers session aliases (used by `notify-hermes` for
sender name resolution) and the `default_sender` config:

```yaml
callbacks:
  - match_type: task_error
    print: false
    context: true
    command: "notify-send 'Task failed'"

  - match_type: task_done
    print: false
    context: true
    command: "afplay ~/sounds/done.mp3"
```

Two boolean fields control behavior: `print` (terminal output), `context` (inject into LLM context).

The `command` field receives these environment variables:
- `MESSAGE` — full message JSON
- `TYPE` — message type
- `FROM` — sender endpoint name
- Stdin — raw message JSON (for backward compatibility)

Example callback scripts are bundled in `examples/`:

```bash
examples/macos-notify.py    # macOS notification via osascript
examples/play-sound.py      # Play random sound via afplay  
examples/slack-notify.sh    # Slack webhook (set SLACK_WEBHOOK_URL)
```

## Architecture

```
notify-hermes ──→ hermes-bus (Unix Socket)
notify-agent  ──→ tmux send-keys

Message routing (print/inject/command) is handled by hermes-bus-plugin
via ~/.hermes/bus-rules.yaml.
```

## Session Aliases

Map tmux session names to human-readable sender names in `notify.yaml`:

```yaml
session_aliases:
  session-1: alias-1
  session-2: alias-2

default_sender: notify-agent
```
