Wmux

Created by @HaD0Yun · Maintained under NomaDamas

🔔 Warp alert — native toasts when your AI agent finishes a turn.

Works with Claude Code, Codex CLI, OpenCode, and Gemini CLI.

When the agent finishes a turn, asks for input, or goes idle, you get a real OS notification in Warp's top-right corner. No polling, no daemons — just the agent's own lifecycle hooks firing OSC sequences that Warp natively interprets.

TL;DR

# 1. Open Warp Terminal (notifications need a Warp-attached TTY)
# 2. Install
git clone https://github.com/NomaDamas/warpalert.git ~/.wmux && ~/.wmux/install.sh

# 3. Restart your agent sessions (existing sessions won't fire toasts)
# 4. Run an agent and finish a turn — toast appears in Warp's top-right

For unattended / AI-agent / CI use, pass --yes:

git clone https://github.com/NomaDamas/warpalert.git ~/.wmux && ~/.wmux/install.sh --yes

Prerequisites

Install

Interactive (humans)

git clone https://github.com/NomaDamas/warpalert.git ~/.wmux && ~/.wmux/install.sh

You'll see a "Detected agents" list and a [Y/n] prompt. Press Enter to accept.

Non-interactive (AI agents, CI, scripts)

# Flag form
git clone https://github.com/NomaDamas/warpalert.git ~/.wmux && ~/.wmux/install.sh --yes

# Env form (useful when you can't pass flags, e.g. piping into a shell)
git clone https://github.com/NomaDamas/warpalert.git ~/.wmux && WMUX_YES=1 ~/.wmux/install.sh

Equivalent. Both skip the confirmation prompt.

What the installer modifies

The installer touches only the agents it detects. Every file it writes gets a timestamped .bak-wmux-YYYYMMDD-HHMMSS backup next to it before being changed, and uninstall restores from that record.

Your other hooks in those files are preserved. The installer uses jq for JSON files so existing entries are merged, not overwritten.

Verify

After install, the installer prints a "Heads up" section listing any agent processes that were already running before install — those must be restarted (see below). Then verify the install:

1. Config wiring check

grep -l wmux ~/.claude/settings.json ~/.codex/hooks.json ~/.codex/config.toml \
            ~/.config/opencode/opencode.json ~/.gemini/settings.json 2>/dev/null

Should list one line per detected agent.

2. Smoke test

# Must run from a real terminal. Piped/subshell calls won't have /dev/tty.
~/.wmux/hooks/wmux-event.sh stop claude < /dev/tty
tail -1 ~/.wmux/wmux.log

Expected log line:

[HH:MM:SS] agent=claude event=stop emit=ok proto=1 tty=<...> tty_src=<...> ... osc9='✅ <project> — claude done'

Key fields:

• emit=ok — the OSC sequence was written to a TTY successfully.
• tty_src=dev_tty — wrote to the calling shell's controlling TTY. Normal for direct-from-Warp invocation.
• tty_src=pane_tty — wrote to the tmux pane TTY. Normal when running inside tmux.
• tty_src=session_client or any_client — wrote to an attached tmux client TTY (fallback for detached-pane setups).
• tty_src=dev_tty_unreachable — no writable TTY found anywhere. The toast will not appear. See Troubleshooting.

If emit=ok shows up and you're inside a Warp tab, you should see a toast in Warp's top-right at the moment the hook ran.

3. End-to-end check

Start a fresh agent session (after restarting, see next section), make it do one full turn, and watch Warp's top-right.

Restart your agent sessions

Hooks are read at agent startup. Sessions that were already running before install will not fire toasts. Restart each one.

Pick the method that matches how you launched the agent:

To list pre-existing agent processes the installer warned about:

pgrep -af '(^|/)(claude|codex|opencode|gemini)( |$|--)'

Customization

All optional. Set env vars before launching the agent (or in ~/.bashrc / ~/.zshrc).

Toast message templates

{project} is replaced with the agent's CWD basename. {agent} is replaced with the agent name (claude, codex, opencode, gemini).

export WMUX_TOAST_STOP='✅ {project} — {agent} done'                  # default
export WMUX_TOAST_PERMISSION='⚠️ {project} — {agent} needs input'    # default
export WMUX_TOAST_IDLE='💬 {project} — {agent} waiting'              # default

Codex notify chaining

If you already had notify = [...] set in ~/.codex/config.toml before install (for example, oh-my-codex users), the installer parses your previous argv and persists it to ~/.wmux/state/codex-inner.argv. The Wmux bridge auto-chains to it on every invocation, so your previous notify handler keeps firing alongside Wmux with no manual setup.

Override:

# Force a specific inner handler (overrides the auto-chain state file)
export WMUX_CODEX_INNER=/path/to/your/notify-hook.js
export WMUX_CODEX_INNER_INTERP=node   # optional; inferred from .js suffix

Logging

export WMUX_LOG_FILE="$HOME/.wmux/wmux.log"   # default
export WMUX_LOG_MAX_BYTES=131072              # default; rotates to .1 above this

Troubleshooting

Toast doesn't appear in Warp

Walk this list top to bottom — it matches the order Wmux needs things to work.

emit=fail tty=/dev/tty err=... No such device

You ran the smoke test from a piped subshell (<<< or echo ... |). That closes /dev/tty. Use the documented form:

~/.wmux/hooks/wmux-event.sh stop claude < /dev/tty

Codex's previous notify handler stopped firing

The bridge auto-chains via ~/.wmux/state/codex-inner.argv. If that file is missing or empty, the installer failed to parse your previous notify = [...] line. Restore it manually:

# Inspect what the installer captured
cat ~/.wmux/state/codex-inner.argv

# Or override via env var (one token per argv element, joined by spaces)
export WMUX_CODEX_INNER=/your/handler.js
export WMUX_CODEX_INNER_INTERP=node

"Already-running agents detected" warning at install time

This is expected if you had any agent running before install. Restart those processes — the hooks only load at startup.

Uninstall

~/.wmux/install.sh --uninstall

What it does:

1. Removes Wmux entries from every detected agent's config (Claude / Codex / OpenCode / Gemini).
2. Restores ~/.codex/config.toml's notify = [...] to the previous value (recorded at install time in ~/.wmux/state/previous-codex-notify.txt).
3. Removes ~/.wmux/state/codex-inner.argv (auto-chain state).
4. Leaves your other hooks alone.

Then delete the install dir:

rm -rf ~/.wmux

The ~/.tmux.conf allow-passthrough line is not removed automatically — it's a generally useful setting and uninstall keeps it. Remove it manually if you want:

sed -i '/# Wmux: required so OSC 9/,+1d' ~/.tmux.conf

How it works (one paragraph)

Each supported agent has a hook system that fires on lifecycle events (SessionStart, Stop, PermissionRequest, etc.). The installer wires those hooks to call ~/.wmux/wmux-event.sh, which writes two escape sequences to a TTY: OSC 777 (Warp's CLI Agent Protocol — adds a sidebar entry) and OSC 9 (iTerm-style desktop toast — Warp shows it in the top-right). Codex CLI doesn't expose a Stop hook, so Wmux bridges through ~/.codex/config.toml's notify directive instead. To survive detached-tmux setups (e.g. OMX, tmuxinator), the hook walks fallbacks: /dev/tty → tmux pane TTY → attached tmux client TTY anywhere.

MIT — see LICENSE. Issues and PRs welcome at NomaDamas/warpalert.