WispTerm Notify Setup
Overview
Install a small notifier that makes Claude Code and Codex surface a WispTerm
notification (OSC 777 toast + terminal bell badge) when a turn finishes or a
confirmation is needed. The notifier is agent-agnostic and the installers are
idempotent — safe to re-run.
Workflow
Determine the target from the user's words and WispTerm state.
- If the user names an existing WispTerm tab/server/profile (for example
CPU3), call terminal_list first and match by title/kind.
- If a saved SSH profile is named but no SSH tab is already open, call
ssh_profile_connect {"profile_name":"<name>"} and use the returned
surface_id.
- Never ask the user to re-provide SSH host/user/port/password when the
target is an existing saved WispTerm profile. Ask only if the profile is
missing or authentication fails.
Install using the target-specific transfer path.
Local POSIX / macOS / WSL: copy the bundled POSIX scripts directly to
the target shell, then run:
sh ./install-wispterm-notify.sh
When targeting an already-open WSL surface, use wsl_session_exec to run
commands in that surface. Do not use scp for WSL.
Local Windows PowerShell: copy the bundled PowerShell scripts directly
to the Windows profile and run install-wispterm-notify.ps1 with
powershell_exec:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install-wispterm-notify.ps1
Remote saved SSH profile: use scp, not pasted heredocs, to transfer
the bundled POSIX scripts to the remote server, then run the POSIX
installer in that SSH session. From Windows/WispTerm, prefer the bundled
profile-aware helper because it reads %APPDATA%\wispterm\ssh_hosts,
decodes the saved profile, supports saved-password profiles via
SSH_ASKPASS, and uses scp.exe/ssh.exe without connection sharing:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install-wispterm-notify-remote.ps1 -ProfileName "CPU3"
If you are already inside the SSH tab, you may run the final installer
with ssh_session_exec after the scp upload.
Relay what it changed: the notify program path
(~/.config/wispterm/wispterm-notify.sh on POSIX/remote,
%APPDATA%\wispterm\wispterm-notify.ps1 on Windows), which Claude Code hooks
were added vs already present, and whether Codex's notify was added,
already set, or left untouched (a pre-existing different notify is never
overwritten).
Verify — run the printed test command and ask the user to confirm they saw a
bell badge / toast in WispTerm:
echo '{"hook_event_name":"Notification","title":"WispTerm","message":"setup ok"}' \
| ~/.config/wispterm/wispterm-notify.sh
WeChat forwarding (optional)
In addition to the in-terminal toast/bell, WispTerm can forward each agent
finish / confirmation notification to a WeChat account you've already bound to
WispTerm's built-in iLink direct connection — no third-party relay.
Prerequisites (all required):
- A WispTerm build that includes notification → WeChat forwarding.
weixin-direct-enabled = true in your WispTerm config.- Scan the QR (WispTerm's WeChat panel) to bind your WeChat account.
- Set
weixin-allowed-user = <your iLink user id> — forwarding needs a bound
owner as the push destination. The "auto-bind the first sender as owner" path
is not yet wired, so the owner must be set explicitly here; while it is empty,
pushes are silently skipped.
weixin-notify-forward = true in your WispTerm config.- Keep
desktop-notifications = on (default) — forwarding rides the same
notification pipeline and is skipped when desktop notifications are off.
Behavior: a push is sent only when the notification is from this notifier,
the binding is live with a bound owner, and you are not actively viewing
that pane (window unfocused, or a different tab/split). The phone message is
<title>\n<body>, e.g. Claude Code / 完成，轮到你了.
Verify: run the test command below to trigger one notification while the
WispTerm window is unfocused, and confirm the message arrives in WeChat.
Notes
- Where it shows: only when Claude Code / Codex run inside WispTerm. The
rich OSC 777 toast needs a WispTerm build with OSC 9/777 support; older builds
still get the bell badge from the BEL.
- Idempotent: re-running won't duplicate hooks; existing hooks and a
pre-existing Codex
notify are preserved.
- Backups:
settings.json.bak / config.toml.bak are written before edits.
- Dependencies: the POSIX installer prefers
python3 for the JSON merge,
falls back to jq, then to printing a manual snippet. The PowerShell
installers use built-in PowerShell JSON/text handling.
- SSH transfers: keep OpenSSH stderr visible. Do not add
ControlMaster/ControlPersist/ControlPath to ssh.exe/scp.exe.
1---2name: wispterm-notify-setup3description: Use when the user wants to install, repair, or re-apply WispTerm notification reminders (Claude Code Stop + Notification, and Codex turn-complete) in a local WSL/macOS/Linux/PowerShell shell or a saved WispTerm SSH profile, so finishes and confirmation prompts surface inside WispTerm.4---56# WispTerm Notify Setup78## Overview910Install a small notifier that makes Claude Code and Codex surface a WispTerm11notification (OSC 777 toast + terminal bell badge) when a turn finishes or a12confirmation is needed. The notifier is agent-agnostic and the installers are13idempotent — safe to re-run.1415## Workflow16171. Determine the target from the user's words and WispTerm state.1819 - If the user names an existing WispTerm tab/server/profile (for example20 `CPU3`), call `terminal_list` first and match by `title`/`kind`.21 - If a saved SSH profile is named but no SSH tab is already open, call22 `ssh_profile_connect {"profile_name":"<name>"}` and use the returned23 `surface_id`.24 - Never ask the user to re-provide SSH host/user/port/password when the25 target is an existing saved WispTerm profile. Ask only if the profile is26 missing or authentication fails.27282. Install using the target-specific transfer path.2930 - **Local POSIX / macOS / WSL:** copy the bundled POSIX scripts directly to31 the target shell, then run:3233 ```bash34 sh ./install-wispterm-notify.sh35 ```3637 When targeting an already-open WSL surface, use `wsl_session_exec` to run38 commands in that surface. Do not use `scp` for WSL.3940 - **Local Windows PowerShell:** copy the bundled PowerShell scripts directly41 to the Windows profile and run `install-wispterm-notify.ps1` with42 `powershell_exec`:4344 ```powershell45 powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install-wispterm-notify.ps146 ```4748 - **Remote saved SSH profile:** use `scp`, not pasted heredocs, to transfer49 the bundled POSIX scripts to the remote server, then run the POSIX50 installer in that SSH session. From Windows/WispTerm, prefer the bundled51 profile-aware helper because it reads `%APPDATA%\wispterm\ssh_hosts`,52 decodes the saved profile, supports saved-password profiles via53 `SSH_ASKPASS`, and uses `scp.exe`/`ssh.exe` without connection sharing:5455 ```powershell56 powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install-wispterm-notify-remote.ps1 -ProfileName "CPU3"57 ```5859 If you are already inside the SSH tab, you may run the final installer60 with `ssh_session_exec` after the `scp` upload.61623. Relay what it changed: the notify program path63 (`~/.config/wispterm/wispterm-notify.sh` on POSIX/remote,64 `%APPDATA%\wispterm\wispterm-notify.ps1` on Windows), which Claude Code hooks65 were added vs already present, and whether Codex's `notify` was added,66 already set, or left untouched (a pre-existing different `notify` is never67 overwritten).68694. Verify — run the printed test command and ask the user to confirm they saw a70 bell badge / toast in WispTerm:7172 ```bash73 echo '{"hook_event_name":"Notification","title":"WispTerm","message":"setup ok"}' \74 | ~/.config/wispterm/wispterm-notify.sh75 ```7677## WeChat forwarding (optional)7879In addition to the in-terminal toast/bell, WispTerm can forward each agent80finish / confirmation notification to a WeChat account you've already bound to81WispTerm's built-in iLink direct connection — no third-party relay.8283**Prerequisites (all required):**841. A WispTerm build that includes notification → WeChat forwarding.852. `weixin-direct-enabled = true` in your WispTerm config.863. Scan the QR (WispTerm's WeChat panel) to bind your WeChat account.874. Set `weixin-allowed-user = <your iLink user id>` — forwarding needs a bound88 owner as the push destination. The "auto-bind the first sender as owner" path89 is not yet wired, so the owner must be set explicitly here; while it is empty,90 pushes are silently skipped.915. `weixin-notify-forward = true` in your WispTerm config.926. Keep `desktop-notifications = on` (default) — forwarding rides the same93 notification pipeline and is skipped when desktop notifications are off.9495**Behavior:** a push is sent only when the notification is from this notifier,96the binding is live with a bound owner, and you are **not** actively viewing97that pane (window unfocused, or a different tab/split). The phone message is98`<title>\n<body>`, e.g. `Claude Code` / `完成，轮到你了`.99100**Verify:** run the test command below to trigger one notification while the101WispTerm window is unfocused, and confirm the message arrives in WeChat.102103## Notes104105- **Where it shows:** only when Claude Code / Codex run *inside* WispTerm. The106 rich OSC 777 toast needs a WispTerm build with OSC 9/777 support; older builds107 still get the bell badge from the BEL.108- **Idempotent:** re-running won't duplicate hooks; existing hooks and a109 pre-existing Codex `notify` are preserved.110- **Backups:** `settings.json.bak` / `config.toml.bak` are written before edits.111- **Dependencies:** the POSIX installer prefers `python3` for the JSON merge,112 falls back to `jq`, then to printing a manual snippet. The PowerShell113 installers use built-in PowerShell JSON/text handling.114- **SSH transfers:** keep OpenSSH stderr visible. Do not add115 `ControlMaster`/`ControlPersist`/`ControlPath` to `ssh.exe`/`scp.exe`.
xuzhougeng