Terminal Notification Enhanced

Turn terminal messages into native system notifications you can click to jump back to the right terminal.

• Stay in the editor and never miss long-running tasks. 🔔
• Click once to focus the exact integrated terminal that sent the alert. 🖱️
• Works the same with local and remote terminals over SSH. 🌐

This is a fork of Terminal Notification by Pan Wenbo, with additional fixes and features — macOS notification fixes, reliable click-to-focus via a vscode:// deep link, and new settings like sound and timeout. See the changelog for everything that has changed since the fork.

What you get

• Support for two common notification escape sequences: OSC 9;<message> and OSC 777;notify;<title>;<message>.
• Native notifications on macOS, Windows, and Linux, with a VS Code fallback when the OS cannot send clicks back.
• tmux passthrough handled automatically, so sequences forwarded by tmux still work.

Tip: Many build tools, test runners, and cloud development tools can emit these sequences to announce status.

Quick start

1. Install Terminal Notification Enhanced from the VS Code Marketplace or sideload the .vsix.
2. Run a command that emits a supported sequence from your terminal.
3. Click the notification to focus the emitting terminal tab in VS Code.

Examples you can try

# Simple body-only notification (OSC 9)
printf '\e]9;Build finished\e\\'        # ST terminator
# or
printf '\e]9;Build finished\a'          # BEL terminator

# Title + body (OSC 777)
printf '\e]777;notify;Nightly Tests;All suites passed\a'

# Through tmux passthrough
printf '\ePtmux;\e\e]777;notify;Deploy;Production complete\a\e\\'

What are “OSC sequences”?

OSC stands for Operating System Command. It is a family of escape sequences that terminals interpret as requests, such as setting a window title or asking for a desktop notification. This extension listens to the shell execution stream exposed by VS Code and turns the two sequences above into notifications.

Remote and tmux

• Remote: Works with VS Code Remote over SSH because parsing happens on the client side in the editor.
• tmux: The extension unwraps tmux passthrough so that sequences forwarded by tmux continue to be recognized.

Settings

All settings live under Terminal Notification Enhanced (terminalNotification.*).

• terminalNotification.preferOsNotifications default true. Use native OS notifications. Disable to use VS Code toasts only.
• terminalNotification.notifierPath default empty (macOS only). Absolute path to a terminal-notifier >= 2.x binary. An external binary is used only when this is set; otherwise the legacy copy bundled with node-notifier is used. Requires a window reload to take effect.
• terminalNotification.showVsCodeNotification default true. Show a VS Code toast alongside OS notifications.
• terminalNotification.ignoreProgressOsc9_4 default true. Ignore OSC 9;4 progress updates to reduce noise.
• terminalNotification.skipWhenActive default false. Skip the notification when VS Code is focused and the emitting terminal is the currently active terminal. Useful for REPL-style tools (e.g. Claude Code) that emit OSC 9 on every response — no notification needed when you are already watching the terminal.
• terminalNotification.sound default default. Play a sound with the OS notification. macOS: system sound names like Glass, Ping, Hero, Submarine, or default for the system default. Windows: IM, Mail, Reminder, SMS, etc. Linux: not supported. Set to empty (or none) for no sound.
• terminalNotification.soundOsx / terminalNotification.soundWindows default empty. Platform-specific overrides for terminalNotification.sound, applied instead of the base value when set. Sound names differ per platform, so these let a Settings Sync'd configuration pick a valid sound on each OS. Accept the same values as the base setting plus none for no sound; leave empty to inherit the base setting. There is no soundLinux — Linux notifications cannot play sounds.
• terminalNotification.timeout default 0. Seconds an OS notification stays visible before it is auto-dismissed. 0 means no timeout: notifications remain until you click or dismiss them (where the platform supports it). On macOS with the bundled legacy notifier, clicks are only forwarded while the helper process is alive, so it always runs with a numeric timeout — your value when set, otherwise an internal 1-hour window; after that window the notification is removed and clicks fall back to the vscode:// deep link. Windows does not support custom durations.

Commands:

• Notification: Enable — resume parsing terminal output.
• Notification: Disable — pause parsing without unloading the extension.

Compatibility

• VS Code 1.93 or newer.
• Shell Integration must be enabled in your integrated terminal. This is the default for supported shells.

macOS

macOS notifications are sent with terminal-notifier:

1. The legacy copy bundled with node-notifier (default). It supports click-to-focus of the exact terminal tab, but it must never receive -sender; on recent macOS versions (13+) that combination hangs forever inside a permission request, which is why this extension no longer passes -sender on any backend. Clicks are only forwarded while the helper process is alive, so it always runs with a numeric timeout: your terminalNotification.timeout when set, otherwise an internal 1-hour window (default 0). During that window clicks focus the terminal directly; the notification is removed when the window closes. Clicks after the window — or on notifications older than the most recent one — fall back to a persisted vscode:// deep link. The link is resolved through vscode.env.asExternalUri, which stamps it with the sending window's ID, so VS Code delivers it to the originating window even when another VS Code window is frontmost; it requires the extension to be installed in that window.
2. A modern terminal-notifier >= 2.x, used only if you point terminalNotification.notifierPath at one, e.g. Homebrew's /usr/local/bin/terminal-notifier or /opt/homebrew/bin/terminal-notifier. Clicking a banner activates VS Code and focuses the originating window and terminal tab through the same vscode:// deep link as the bundled backend (2.x supports -open alongside -activate).

For the most reliable experience on recent macOS versions: brew install terminal-notifier, then set terminalNotification.notifierPath to its path.

Notes and limitations

• Some Linux environments cannot route notification click events back to the app. The extension opens a deep link to return focus to the right terminal as a fallback.
• Icons shown in OS notifications follow the host platform’s rules.

Development

npm install
npm run watch   # or: npm run compile
# press F5 in VS Code to launch an Extension Development Host

License

MIT © Pan Wenbo