Notification Hooks

@daandden/notification-hooks is an installable OMP plugin that forwards selected hook lifecycle events to a shell command.

v1 emits two events:

• ask_waiting when the ask tool is waiting for user input
• completion when an agent run has fully settled after retries and auto-compaction

The hook sends the structured payload on stdin and mirrors key metadata through OMP_NOTIFY_* environment variables.

Install

omp plugin install @daandden/notification-hooks

Configure

Set the command and optional behavior with omp plugin config commands:

omp plugin config set @daandden/notification-hooks command 'notify-send "$OMP_NOTIFY_EVENT" "$OMP_NOTIFY_MESSAGE"'
omp plugin config set @daandden/notification-hooks shell /bin/sh
omp plugin config set @daandden/notification-hooks timeoutMs 5000
omp plugin config set @daandden/notification-hooks notifyOnCompletion true
omp plugin config set @daandden/notification-hooks notifyOnAsk true

Inspect current settings:

omp plugin config list @daandden/notification-hooks

Settings

| Setting | Type | Default | Purpose | | --- | --- | --- | --- | | command | string | disabled | Shell command to run. Empty or unset disables notifications. | | shell | string | /bin/sh | Shell binary used to execute command. | | timeoutMs | number | 5000 | Maximum time before the subprocess is killed and logged as a warning. | | notifyOnCompletion | boolean | true | Emit completion notifications. | | notifyOnAsk | boolean | true | Emit ask_waiting notifications. |

Environment variables

Each setting also has an env fallback:

• OMP_NOTIFICATION_COMMAND
• OMP_NOTIFICATION_SHELL
• OMP_NOTIFICATION_TIMEOUT_MS
• OMP_NOTIFICATION_NOTIFY_ON_COMPLETION
• OMP_NOTIFICATION_NOTIFY_ON_ASK

Every notification subprocess receives these payload-derived env vars:

• OMP_NOTIFY_EVENT
• OMP_NOTIFY_MESSAGE
• OMP_NOTIFY_CWD
• OMP_NOTIFY_TIMESTAMP
• OMP_NOTIFY_SESSION_NAME
• OMP_NOTIFY_SESSION_FILE
• OMP_NOTIFY_TOOL_NAME
• OMP_NOTIFY_QUESTION_COUNT

Example commands

macOS via osascript

omp plugin config set @daandden/notification-hooks command 'osascript -e "display notification \"$OMP_NOTIFY_MESSAGE\" with title \"OMP\" subtitle \"$OMP_NOTIFY_EVENT\""'

Linux via notify-send

omp plugin config set @daandden/notification-hooks command 'notify-send "$OMP_NOTIFY_EVENT" "$OMP_NOTIFY_MESSAGE"'

Webhook bridge

omp plugin config set @daandden/notification-hooks command 'payload=$(cat); jq -n --argjson body "$payload" '{"'"'text'"'": $body.message, "'"'event'"'": $body.event, "'"'session'"'": $body.session}' | curl -fsS -H '"'"'content-type: application/json'"'"' -d @- https://example.invalid/hooks/omp'

Capture payloads to disk

omp plugin config set @daandden/notification-hooks command 'cat > /tmp/omp-notify.json'

JSON payload

Example ask_waiting payload:

{
  "event": "ask_waiting",
  "message": "Demo session: Waiting for input",
  "timestamp": 1742371200000,
  "cwd": "/workspace/project",
  "session": {
    "name": "Demo session",
    "file": "/workspace/.omp/agent/sessions/demo.jsonl"
  },
  "toolName": "ask",
  "ask": {
    "questionCount": 1,
    "questions": [
      {
        "id": "deploy",
        "question": "Ship this change?",
        "options": ["Yes", "No"],
        "multi": false,
        "recommended": 0
      }
    ]
  }
}

Example completion payload:

{
  "event": "completion",
  "message": "Complete",
  "timestamp": 1742371205000,
  "cwd": "/workspace/project",
  "session": {
    "file": "/workspace/.omp/agent/sessions/demo.jsonl"
  }
}

Lifecycle behavior

Completion notifications are intentionally deferred. The hook treats agent_end as a completion candidate, then cancels or reschedules based on follow-up lifecycle events:

• cancel on auto_retry_start
• cancel on auto_compaction_start
• cancel on turn_start
• cancel on session_shutdown
• reschedule on auto_retry_end when success === false
• reschedule on auto_compaction_end when willRetry === false and the context is still idle with no queued messages

This prevents false-positive completion notifications during retry or auto-compaction recovery.

Manual smoke test

1. Install the plugin: omp plugin install @daandden/notification-hooks
2. Configure a capture command: omp plugin config set @daandden/notification-hooks command 'cat > /tmp/omp-notify.json'
3. Trigger an ask flow and confirm /tmp/omp-notify.json contains an ask_waiting payload.
4. Let the agent fully settle and confirm the file contains exactly one final completion payload, not an intermediate retry or compaction payload.
5. If the command fails or times out, inspect ~/.omp/logs/omp.YYYY-MM-DD.log for warning entries.

Failure behavior

Notification subprocess failures are non-fatal. Non-zero exit codes, spawn errors, and timeouts are logged through @oh-my-pi/pi-utils, but they do not fail or block the agent workflow.