Wispterm Notify Setup
Apps & Automationwispterm-notify-setupWispterm Notify Setup is an Agent Skill for apps & automation published in the xuzhougeng/wispterm repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/xuzhougeng/wispterm/blob/HEAD/plugins/skills/wispterm-notify-setup/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/wispterm-notify-setup, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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), callterminal_listfirst and match bytitle/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 returnedsurface_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.
- If the user names an existing WispTerm tab/server/profile (for example
-
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.shWhen targeting an already-open WSL surface, use
wsl_session_execto run commands in that surface. Do not usescpfor WSL. -
Local Windows PowerShell: copy the bundled PowerShell scripts directly to the Windows profile and run
install-wispterm-notify.ps1withpowershell_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 viaSSH_ASKPASS, and usesscp.exe/ssh.exewithout 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_execafter thescpupload.
-
-
Relay what it changed: the notify program path (
~/.config/wispterm/wispterm-notify.shon POSIX/remote,%APPDATA%\wispterm\wispterm-notify.ps1on Windows), which Claude Code hooks were added vs already present, and whether Codex'snotifywas added, already set, or left untouched (a pre-existing differentnotifyis 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 = truein 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 = truein 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
notifyare preserved. - Backups:
settings.json.bak/config.toml.bakare written before edits. - Dependencies: the POSIX installer prefers
python3for the JSON merge, falls back tojq, 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/ControlPathtossh.exe/scp.exe.