Skip to content

Warp "Silent" CLI-Agent Notifications: Check warp.log for OSC 777 Before Blaming the Plugin

A CLI-agent notification plugin for Warp (e.g. a hook that emits an OSC 777 terminal escape sequence when a long-running agent needs attention) can appear completely broken — no banner, no sound — while every part of the plugin chain checks out. Before debugging the plugin itself, check whether Warp actually received the notification.

Symptoms

  • No visible notification banner when an agent finishes or needs input.
  • The notification hook/gate script itself passes every check: the permission gate is open, jq is installed and parses correctly, the emitted terminalSequence JSON is well-formed.
  • This looks exactly like "the plugin isn't firing" — but the plugin, gate, and JSON payload are all fine.

Root Cause

Warp does not raise a visible banner for a notification if the tab that triggered it is the one currently focused/visible to the user. The OSC 777 sequence is still received and processed — Warp's own notification-suppression policy (not showing a banner for a tab you're already looking at) is what makes it look like nothing happened.

Diagnosis

Check Warp's own log for confirmation that the sequence arrived, rather than re-auditing the hook chain:

tail -f ~/Library/Logs/warp.log

Trigger the notification again and look for a line like:

Received OSC 777 notification: title=Some("warp://cli-agent")

If that line appears, delivery worked. The notification reached Warp; the absence of a banner is a display/focus policy, not a broken integration. warp.log is the ground truth here — it tells you definitively whether the escape sequence was received, independent of whether a banner was shown.

Fix / What To Actually Check

  • If warp.log shows the OSC 777 line was received: nothing to fix in the plugin. Switch to a different tab (or defocus the window) and re-trigger to confirm the banner appears when the tab isn't the one in focus — that confirms the suppression theory rather than a real bug.
  • If warp.log shows no OSC 777 line at all: now the hook chain is worth auditing (gate script, jq availability, malformed terminalSequence JSON, the hook not actually running).

Addendum (2026-08-02): the log line proves delivery, not rendering

The Received OSC 777 line means Warp received the notification — it does not mean Warp will ever show one. On a Windows/WSL host, notifications vanished entirely (focused or not) while warp.log showed every event arriving in real time. The cause was simply Warp's own notification setting being off — and the gap had been invisible for months because a hand-rolled PowerShell toast hook was raising native Windows notifications in parallel, masking the fact that the plugin's banners never rendered. Removing the "redundant" hook exposed it.

So the full checklist, in order:

  1. warp.log shows no OSC 777 line → audit the hook chain (as above).
  2. Log line present, no banner ever, any focus state → check Warp Settings → Notifications (and, on Windows, Settings → System → Notifications → Warp, plus Focus Assist/DND).
  3. Log line present, banners appear only for unfocused tabs → working as designed (the focused-tab suppression above).

Corollary: before deleting a "redundant" second notification path, disable it temporarily and confirm the surviving path actually renders — two paths that both fire are not necessarily two paths that both display.

Notes

  • This is the same debugging pattern as macOS: Repeating Alert Tone from Mirrored iPhone Notification — check the actual delivery log for the subsystem in question before assuming the most visible/obvious component (the plugin, the app) is at fault.
  • Don't confuse this with a genuinely separate notification mechanism on another platform (e.g. a WSL-side toast helper) — if a fleet has more than one shell environment reporting notification issues, verify each one's actual delivery log independently rather than assuming they share a root cause.