Codex Notifier

Reliable completion and error notifications for Codex workflows in VS Code.

A lightweight VS Code extension that notifies you when Codex responses finish or pauses for input using sound and configurable UI alerts that follow the same quiet-status vs banner setting.

Note

Built for fast feedback loops: use automatic Codex session completion detection or the manual .codex-notify file trigger.

Features

• Completion and error notification commands.
• Bundled sound defaults (no custom setup required):
  • Complete -> notification2.wav
  • Error -> notification1.wav
• Auto completion detection from Codex stream logs with safer burst checks.
• Prompt detection when Codex pauses for request_user_input.
• Optional document-based idle detection fallback.
• Quiet mode or banner mode for completion and prompt notifications.
• Windows toast click focus for the exact VS Code window that owns the prompt, including multiple windows using the same existing Codex chat.
• Manual trigger support through .codex-notify and codex-done.ps1.
• Remote SSH workspace support: notifications and sounds run locally while relative trigger files are watched on the remote host.

Commands

Command	Description
Codex Notifier: Notify Complete	Trigger completion notification manually
Codex Notifier: Notify Error	Trigger error notification manually
Codex Notifier: Test Sound	Test completion sound + UI behavior
Codex Notifier: Toggle Auto Notify	Enable/disable log-based auto detection
Codex Notifier: Show Diagnostics	Show runtime diagnostics snapshot

Installation

Option 1 (Recommended): VS Code Marketplace

1. Open Extensions view in VS Code (Ctrl+Shift+X).
2. Search Codex Notifier.
3. Click Install on zis3c.codex-notifier.

Direct link:

• https://marketplace.visualstudio.com/items?itemName=zis3c.codex-notifier

Option 2: Command Line

code --install-extension zis3c.codex-notifier

Option 3: VSIX (Offline/Manual)

See INSTALLATION.md for VSIX steps.

Quick Start

1. Open VS Code settings and search Codex Notifier.
2. Keep defaults (recommended): sound on, auto-detection on, safer burst thresholds.
3. Run Codex Notifier: Test Sound from Command Palette.
4. Ask Codex something and wait for either response completion or request_user_input notification.
5. If behavior does not match the settings you just changed, check whether this workspace has its own .vscode/settings.json overrides for codexNotifier.*.

Windows Toast Click Focus

On Windows, v0.1.12 enables toast window focus automatically. The extension records the native window target when each VS Code window is focused. Each notification stores its target by Codex session and turn, so clicking a toast returns to the window that sent that prompt, even when several windows use the same existing chat. The helper is fail-safe: if it cannot identify the exact window, it does nothing instead of focusing a different window. Run Codex Notifier: Enable Toast Window Focus (Windows) only to repair a missing protocol registration.

How It Works

1. On activation, the extension starts the Codex session completion detector and the manual file watcher.
2. For manual mode, it resolves codexNotifier.watchFilePath (default: .codex-notify) from the current workspace folder or folders.
3. If no workspace folder is open, it falls back to the current process directory.
4. If the workspace changes, the manual watcher refreshes so it follows the new folder.
5. If the file does not exist, nothing is created automatically (manual trigger stays off until file exists).
6. When the file content changes:
   • Contains error -> error notification
   • Any other non-empty content -> complete notification
7. Auto mode tails Codex session JSONL files and reacts to authoritative task_complete and request_user_input events.
8. Prompt notifications use the same codexNotifier.completionUseBanner setting as completion notifications.
9. On Windows, toast activation uses a per-user codex-notifier:// protocol and a hidden helper. Native HWND mappings and per-turn ownership prevent cross-window redirects and duplicate focus actions.

Remote SSH Workspaces

Codex Notifier remains a single extension running in VS Code's local UI extension host, so sounds and notifications are produced on your computer. In a Remote SSH window it reads ~/.codex/sessions/**/*.jsonl through VS Code's remote file-system API and reacts to authoritative task_complete and request_user_input events. Guardian and subagent sessions are ignored, because their intermediate task_complete events do not mean the user's top-level task has finished. request_user_input events mean Codex is waiting for the user to answer, so they should notify immediately. When a conversation is forked into a new task, inherited completion history is also ignored. Resuming an existing chat does not replay its previous completions; only newly completed work produces a notification.

The default relative trigger path (.codex-notify) is watched through VS Code's remote file-system API. In a multi-root workspace, one trigger is watched in each root. Absolute watchFilePath values still refer to the local UI machine; use a relative path to watch a file on the SSH host.

The remote home directory is inferred from the workspace URI. For unusual layouts, set codexNotifier.remoteSessionsPath to the absolute remote sessions directory.

Recommended Settings

{
  "codexNotifier.enableSound": true,
  "codexNotifier.enablePopup": true,
  "codexNotifier.completionUseBanner": false,
  "codexNotifier.toastWhenUnfocused": true,
  "codexNotifier.monitorCodexLog": true,
  "codexNotifier.codexLogPollMs": 400,
  "codexNotifier.codexLogIdleMs": 500,
  "codexNotifier.codexChatCooldownMs": 4500,
  "codexNotifier.codexLogMinEvents": 1,
  "codexNotifier.codexLogMinBurstMs": 0
}

Documentation

• Tutorial video: https://youtu.be/IpdNMO9YukI
• For sound customization and advanced settings, see INSTALLATION.md and the Recommended Settings section above.
• INSTALLATION.md
• CONTRIBUTING.md
• SECURITY.md
• AUTO_DEPLOY.md

Testing

• Local syntax and release checks:
  • node --check extension.js
  • npm run check
  • npm run lint
  • npm test
  • npm run package:test
  • npm run ci
• Manual smoke test:
  • install the VSIX
  • run Codex Notifier: Test Sound
  • verify the package loads and the commands work
  • test once with VS Code focused and once with VS Code unfocused to confirm banner or quiet mode plus system toast behavior
  • open two or more VS Code windows, use existing chats in each, prompt them, and confirm each toast returns to its originating window
• Manual remote live test:
  • open a Remote SSH VS Code window
  • verify notifications and sound on the local UI machine
  • confirm the remote host session watcher still reacts correctly
• What automation does not cover yet:
  • no full UI E2E test for the VS Code window
  • no automated Remote SSH live test in GitHub Actions
• CI:
  • GitHub Actions runs the same checks on every push and pull request across Windows, macOS, and Linux
  • npm run ci matches the main automated checks locally

Project Structure

codex-notifier-vscode/
|- .eslintrc.cjs               # ESLint config
|- .github/
|  `- workflows/
|     `- ci.yml                # GitHub Actions CI
|- .gitignore                    # Git exclusions for local/dev artifacts
|- .vscodeignore                 # VSIX packaging exclusions
|- .vscode/
|  |- launch.json                # Extension Development Host profile
|  `- settings.json              # Local development settings
|- AUTO_DEPLOY.md                # Release/deploy workflow documentation
|- CHANGELOG.md                  # Version history
|- CONTRIBUTING.md               # Contribution workflow and coding notes
|- INSTALLATION.md               # End-user and dev installation guide
|- LICENSE                       # MIT license
|- README.md                     # Main documentation and feature overview
|- SECURITY.md                   # Security policy and reporting guidance
|- package-lock.json             # Locked npm dependency tree
|- package.json                  # VS Code extension manifest and settings
|- extension.js                  # Core runtime, watchers, and notifications
|- session-events.js             # Codex JSONL event parsing helpers
|- toast-focus.js                # Toast protocol payload builder
|- windows-toast-focus.ps1       # Windows native window focus helper
|- windows-toast-focus.vbs       # Hidden Windows helper launcher
|- codex-done.ps1                # Manual .codex-notify trigger helper
|- notification1.wav             # Bundled error sound
|- notification2.wav             # Bundled completion sound
|- scripts/
|  |- test-session-events.js     # Session event tests
|  |- test-toast-focus.js        # Toast payload tests
|  |- test-vsix.js               # VSIX smoke test
|  `- validate-release.js        # Release validation checks
`- codex-notifier-private.vsix   # Locally built install artifact

Notes:

• .vscode/settings.json is intentionally local-only and not tracked in git.
• .codex-notify is runtime trigger data and not tracked in git.
• codex-notifier-private.vsix is a generated install artifact, not a source file.
• .vscode-test/ is a generated VS Code test runtime and is not part of the source tree or VSIX package.

License

MIT. See LICENSE.