omaherald

Desktop notification hub for terminal AI agents on Omarchy (Arch + Hyprland). When Claude Code, Codex CLI, or opencode finishes a turn, hits an error, or waits on your approval, omaherald raises a toast — custom QML toasts rendered by Omarchy's shell, falling back to notify-send.

Includes a bar widget with an event log panel so you can see what every agent has been up to.

Components

Install

Option A: Omarchy plugin manager + CLI

omarchy plugin add https://github.com/chuma-beep/omaherald.git --enable

This installs and registers the bar widget / toast host. Then grab the CLI:

curl -fsSL https://raw.githubusercontent.com/chuma-beep/omaherald/main/bin/omaherald \
  -o ~/.local/bin/omaherald && chmod +x ~/.local/bin/omaherald

Option B: full install from a clone

git clone https://github.com/chuma-beep/omaherald.git
cd omaherald
./install.sh
omaherald test

install.sh copies all three components into place. To install only the opencode plugin or CLI, copy those files manually.

Uninstall

omarchy plugin remove wisdom.omaherald   # bar widget / toast host (or: rm -rf ~/.config/omarchy/plugins/wisdom.omaherald)
rm ~/.local/bin/omaherald                # CLI
rm ~/.config/opencode/plugins/omaherald.js  # opencode plugin (optional)
rm -rf ~/.local/state/omaherald          # event log (optional)

Nothing in ~/.config/hypr/, your shell layout, or other agent configs is touched; remove any hooks you added from ~/.claude/settings.json / ~/.codex/config.toml if desired.

Requirements:

• Omarchy (for custom toasts via omarchy-shell); otherwise falls back to notify-send
• jq
• Optional: paplay for sounds (sound setting)

Agent hooks

Claude Code

Add to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "omaherald claude stop" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "omaherald claude permission" }] }]
  }
}

Hooks receive the session JSON on stdin; omaherald reads cwd and message from it.

Claude Code fires Notification for more than permission requests (idle waits, plan-mode notices, etc.). Omaherald classifies each message: text mentioning permission or approval raises the amber permission toast; anything else falls back to a neutral question toast showing the actual message, so working in plan mode no longer triggers false "needs approval" flags.

All event fields (agent, project, message) are sanitized by the CLI — control characters stripped, whitespace flattened, length capped — and rendered as plain text by the shell plugin, so markup in agent output is never interpreted.

Codex CLI

In ~/.codex/config.toml:

notify = ["omaherald", "codex"]

Fires on agent-turn-complete.

opencode

install.sh copies the plugin to ~/.config/opencode/plugins/. It notifies on session idle, permission requests, and session errors — deduplicated per turn and suppressed while another top-level session is still busy.

Anything else

Wrap any long-running command:

omaherald run -- npm run build

Or emit directly:

omaherald notify myagent done "build finished" --cwd ~/Projects/foo

Usage

omaherald test                            send a test notification
omaherald notify <agent> <event> [msg] [--cwd D]
                                          generic hook entry point
                                          events: done | error | permission | question
omaherald claude <stop|permission|idle>   Claude Code hook (reads JSON from stdin)
omaherald codex '<json>'                  Codex CLI notify target
omaherald run -- <cmd...>                 wrap any command; toast when it exits

Settings

~/.config/omaherald/settings.json (created/tuned from the bar panel):

{
  "style": "custom",
  "position": "bottom-right",
  "sound": true,
  "min_run_seconds": 5,
  "toast_seconds": 8,
  "sticky_events": []
}

• style: "custom" (Omarchy QML toasts) or "system" (notify-send)
• position: toast placement used by the custom host
• sound: play a freedesktop sound per event type
• min_run_seconds: minimum runtime before omaherald run notifies
• toast_seconds: custom toast lifetime; all custom toasts auto-expire
• sticky_events: event names (done, error, permission, question) whose custom toasts stay on screen until clicked; system-mode toasts always auto-expire

Event history is logged to ~/.local/state/omaherald/events.log (JSON lines).

License

MIT — see LICENSE.