openclaw-tui-notify

openclaw-tui-notify is an OpenClaw plugin for a simple workflow:

you run openclaw tui inside Ghostty
you switch to another app while a reply is still being generated
when the final assistant reply finishes, you get a macOS notification

It intentionally does not notify for idle shells, tool-call intermediates, or background cron/run sessions.

Status

This project is currently optimized for:

macOS
Ghostty as the terminal
OpenClaw TUI sessions
desktop notifications via terminal-notifier

How It Works

The plugin uses two OpenClaw plugin hooks:

before_dispatch
before_message_write

It only continues when all of these are true:

the session looks like a local interactive agent session
the message is an assistant message
stopReason === "stop"
the reply is not empty
the reply is not a tool/thinking/control artifact
the session recently had a matching local user turn

After that, notify-if-away.mjs checks one thing:

is the active app still Ghostty?

If yes, the notification is suppressed. If not, a macOS notification is sent.

Focus Model

This project uses a simple presence check:

Ghostty frontmost or not

It does not currently detect:

which Ghostty tab is focused
which tmux window is focused
which tmux pane originally ran the TUI session

This keeps the behavior predictable:

if Ghostty is still frontmost, suppress the notification
if another app is frontmost, send the notification

The current boundary and future expansion conditions are documented in spec.md.

Prerequisites

OpenClaw with plugin support
Ghostty
macOS Accessibility permission for app-focus detection
terminal-notifier

Homebrew example:

brew install terminal-notifier

Install

Recommended: ClawHub

Available now. This is the most direct install path for OpenClaw users.

openclaw plugins install clawhub:openclaw-tui-notify

ClawHub installs usually land under:

~/.openclaw/extensions/openclaw-tui-notify

Package Install: npm

Available now. OpenClaw will also try npm-safe plugin specs.

openclaw plugins install openclaw-tui-notify

This install path also typically ends up under:

~/.openclaw/extensions/openclaw-tui-notify

Development Install: git clone

Clone the repo anywhere you like, then install the plugin from the repository root:

openclaw plugins install --link --dangerously-force-unsafe-install /absolute/path/to/openclaw-tui-notify

Then restart OpenClaw Gateway.

Configuration

For linked installs, copy config/config.env.example to config.env in the repository root:

cp config/config.env.example config.env

For ClawHub or npm installs, copy the same example into the installed package directory, usually:

cp ~/.openclaw/extensions/openclaw-tui-notify/config/config.env.example \
  ~/.openclaw/extensions/openclaw-tui-notify/config.env

If your OpenClaw installation uses a different extension root, inspect the installed plugin path first:

openclaw plugins inspect openclaw-tui-notify --json

Supported settings:

OPENCLAW_TUI_NOTIFY_ENABLED=true|false
OPENCLAW_TUI_NOTIFY_SOUND=Glass
OPENCLAW_TUI_NOTIFY_DEBUG=true|false
OPENCLAW_TUI_NOTIFY_STATE_DIR=/custom/path
OPENCLAW_TUI_NOTIFY_TERMINAL_NOTIFIER_PATH=/path/to/terminal-notifier
OPENCLAW_TUI_NOTIFY_NON_TUI_CHANNELS=feishu,telegram,...
OPENCLAW_TUI_NOTIFY_SESSION_PREFIXES=agent:
OPENCLAW_TUI_NOTIFY_EXCLUDE_SESSION_TOKENS=:cron:,:run:
OPENCLAW_TUI_NOTIFY_FALLBACK_TITLE=OpenClaw

Default log directory:

macOS: ~/Library/Logs/openclaw-tui-notify
other systems: ~/.local/state/openclaw-tui-notify

Debugging

When OPENCLAW_TUI_NOTIFY_DEBUG=true, the project writes:

debug.log

inside OPENCLAW_TUI_NOTIFY_STATE_DIR.

Each row includes a source field so you can still distinguish plugin-side filtering from notify-script decisions.

These logs use local timestamps with timezone offsets, for example:

2026-04-13T00:22:41.912+08:00

Manual Test

node notify-if-away.mjs "test-session" "This should appear when Ghostty is not frontmost"

Limitations

If you stay in Ghostty but switch to another tab or tmux window, the notification is still suppressed.
OpenClaw currently labels TUI traffic as webchat in some environments, so channel metadata alone is not enough to distinguish browser sessions from terminal TUI sessions.
macOS sleep / Focus modes / notification style can affect whether a banner is visibly shown even when the notification request was successfully sent.

Notes On Session And Channel Matching

Notification titles are derived from the trailing segment of sessionKey, not hardcoded to a fixed session name.
The fallback title is configurable through OPENCLAW_TUI_NOTIFY_FALLBACK_TITLE.
Session targeting is configurable through OPENCLAW_TUI_NOTIFY_SESSION_PREFIXES and OPENCLAW_TUI_NOTIFY_EXCLUDE_SESSION_TOKENS.
Explicit non-TUI channels are configurable through OPENCLAW_TUI_NOTIFY_NON_TUI_CHANNELS.

Repository Layout

index.ts: OpenClaw plugin entry
notify-if-away.mjs: away check + notification sender
package.json: publishable package metadata
openclaw.plugin.json: OpenClaw plugin metadata
config/config.env.example: local config template
spec.md: design notes, constraints, and future directions

License

MIT

OpenClaw TUI Notify