# WispTerm v1.3.0

> **Your terminal can tap you on the shoulder now.** Programs running in WispTerm —
> including Claude Code and Codex via hooks — can pop a native desktop notification
> via OSC 9 / OSC 777, with a graceful titlebar bell-badge fallback. A new
> `wispterm-notify-setup` skill wires Claude Code and Codex to notify you inside
> WispTerm when a turn finishes or a confirmation is waiting.

## Added

- **Desktop notifications (OSC 9 / OSC 777).** Apps running in WispTerm can request a
  desktop notification with a title and body. On **macOS** this shows a native
  `UNUserNotificationCenter` toast; on other platforms — or when notifications aren't
  authorized / WispTerm isn't running as a bundle — it falls back to the titlebar
  **bell badge**.
  - **Focus-aware.** If the window is focused and the notification comes from the
    *active* terminal, no toast pops (just a brief bell flash). Notifications from a
    background tab, or while the window is unfocused, pop a toast **and** leave a
    persistent bell badge on that tab.
  - **Dedup + rate-limit.** At most one notification per second per terminal, plus a
    5-second window suppressing identical title+body — so a chatty program can't flood
    you.
  - **Config toggle** `desktop-notifications` (default **on**). Turning it off ignores
    the whole notification (no toast, no badge); the plain `\a` terminal bell is
    unaffected.
- **`wispterm-notify-setup` skill.** A one-shot, **idempotent** installer that wires
  Claude Code (Stop + Notification hooks) and Codex (turn-complete `notify`) to surface
  a notification *inside* WispTerm when a turn finishes or a confirmation is needed.
  - Installs an agent-agnostic notifier at `~/.config/wispterm/wispterm-notify.sh`.
  - Writes `settings.json.bak` / `config.toml.bak` backups before editing, and **never**
    overwrites a pre-existing Codex `notify`.
  - Unix only (Linux / WSL + macOS); Windows is not yet supported.

## Fixed

- **Startup crash (`os_unfair_lock`).** `Surface.notif_queue` is now initialized at
  construction, fixing an `os_unfair_lock` crash on launch.

## Notes

- Native toasts are **macOS-only**; Windows / Linux / WSL get the bell-badge fallback.
- This release **displays** notifications only — v1 does not render the notification
  body text in the titlebar (badge only), nor route a click back to the source tab.
- The rich OSC 777 toast from the notify skill needs a WispTerm build with OSC 9/777
  support (this release); older builds still get the bell badge from the BEL.
- macOS remains early — prefer Linux or Windows for daily use.

---

# WispTerm v1.3.0（中文）

> **现在终端会主动“拍你肩膀”了。** 在 WispTerm 中运行的程序——包括通过 hook 接入的
> Claude Code 与 Codex——可经 OSC 9 / OSC 777 弹出原生桌面通知,并在其它平台优雅回落到
> 标题栏铃铛 badge。新增的 `wispterm-notify-setup` skill 会把 Claude Code 与 Codex 接线,
> 在一轮结束或有确认等待时在 WispTerm 内提醒你。

## 新增

- **桌面通知(OSC 9 / OSC 777)。** 在 WispTerm 中运行的程序可请求带标题与正文的桌面通知。
  在 **macOS** 上显示原生 `UNUserNotificationCenter` toast;在其它平台——或通知未授权 /
  WispTerm 非 bundle 运行时——回落到标题栏**铃铛 badge**。
  - **尊重焦点。** 窗口聚焦且通知来自*当前活动*终端时,不弹 toast(仅铃铛短闪);来自后台
    标签页、或窗口失焦时,弹出 toast **并**在该标签页常驻铃铛 badge。
  - **去重 + 限流。** 每个终端每秒至多一条,另对相同标题+正文用 5 秒窗口去重——避免聒噪
    程序把你淹没。
  - **配置开关** `desktop-notifications`(默认**开**)。关闭后整条通知被忽略(不弹、不置
    badge);裸 `\a` 终端响铃不受影响。
- **`wispterm-notify-setup` skill。** 一次性、**幂等**的安装器,把 Claude Code(Stop +
  Notification hook)与 Codex(回合结束 `notify`)接线,在一轮结束或需要确认时于 WispTerm
  *内部*弹出提醒。
  - 在 `~/.config/wispterm/wispterm-notify.sh` 安装一个与 agent 无关的通知器。
  - 改动前写入 `settings.json.bak` / `config.toml.bak` 备份,且**绝不**覆盖已存在的 Codex
    `notify`。
  - 仅限 Unix(Linux / WSL + macOS);暂不支持 Windows。

## 修复

- **启动崩溃(`os_unfair_lock`)。** `Surface.notif_queue` 现在在构造时初始化,修复了启动
  时的 `os_unfair_lock` 崩溃。

## 说明

- 原生 toast **仅限 macOS**;Windows / Linux / WSL 回落到铃铛 badge。
- 本版本仅**显示**通知——v1 不在标题栏渲染通知正文(仅铃铛),也不把点击路由回来源标签页。
- 通知 skill 的富 OSC 777 toast 需要支持 OSC 9/777 的 WispTerm 构建(即本版本);更旧的
  构建仍可由 BEL 获得铃铛 badge。
- macOS 仍处于早期阶段,日常使用建议优先 Linux 或 Windows。
