Esamtrade 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 using sound and configurable UI alerts (quiet status or banner popup).

[!NOTE] Built for fast feedback loops: you can use auto-detection from Codex logs/chat, or manual file-trigger flow via .codex-notify.

[!IMPORTANT] This is an internal Esamtrade-maintained fork of zis3c/Codex-notifier-vscode, published under the Esamtrade publisher for supply-chain control. It is functionally identical to upstream, rebranded only where required.

Privacy

This extension runs entirely on your machine. It reads local VS Code/Cursor Codex.log activity and the length (not the content) of Codex chat documents purely to detect when a response has finished. It does not transmit logs, prompts, code, or telemetry anywhere, and it makes no network requests. Sound playback uses local OS tools only (powershell.exe on Windows, afplay on macOS, paplay on Linux).

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.
Optional document-based idle detection fallback.
Quiet mode or banner mode for completion notifications.
Manual trigger support through .codex-notify and codex-done.ps1.

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
`Codex Notifier: Debug Snapshot`	Print active docs/editors to output channel

Installation

Option 1 (Recommended): VS Code Marketplace

Open Extensions view in VS Code (Ctrl+Shift+X).
Search Esamtrade Codex Notifier.
Click Install on Esamtrade.esamtrade-codex-notifier.

Direct link:

https://marketplace.visualstudio.com/items?itemName=Esamtrade.esamtrade-codex-notifier

Option 2: Command Line

code --install-extension Esamtrade.esamtrade-codex-notifier

Option 3: VSIX (Offline/Manual)

See INSTALLATION.md for VSIX steps.

Quick Start

Open VS Code settings and search Codex Notifier.
Keep defaults (recommended): sound on, auto-detection on.
Run Codex Notifier: Test Sound from Command Palette.
Ask Codex something and wait for response completion notification.

How It Works

On activation, the extension starts auto-detection watchers (Codex log/chat) and the manual file watcher.
For manual mode, it resolves codexNotifier.watchFilePath (default: .codex-notify) from your workspace root.
If no workspace folder is open, it falls back to the current process directory.
If the file does not exist, nothing is created automatically (manual trigger stays off until file exists).
When the file content changes:
- Contains error -> error notification
- Any other non-empty content -> complete notification
Auto mode can notify completion directly from Codex stream activity, so manual file writes are optional.

Recommended Settings

{
  "codexNotifier.enableSound": true,
  "codexNotifier.enablePopup": true,
  "codexNotifier.completionUseBanner": false,
  "codexNotifier.monitorCodexLog": true,
  "codexNotifier.codexLogPollMs": 500,
  "codexNotifier.codexLogIdleMs": 900,
  "codexNotifier.codexChatCooldownMs": 4500
}

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
UPLOAD.md — Marketplace publishing & upstream-merge guide

Project Structure

codex-finish-notifier-vscode/
|- .gitignore                    # Git exclusions for local/dev artifacts
|- .vscodeignore                 # VSIX packaging exclusions
|- AUTO_DEPLOY.md                # Release/deploy workflow documentation
|- 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
|- package.json                  # VS Code extension manifest/config schema
|- extension.js                  # Core extension runtime (commands + watchers)
|- codex-done.ps1                # Helper trigger script for .codex-notify flow
|- notification1.wav             # Bundled default sound (error)
|- notification2.wav             # Bundled default sound (complete)
|- UPLOAD.md                     # Marketplace publishing + upstream-merge guide
`- .vscode/
   `- launch.json                # Extension Development Host debug profile

Notes:

.vscode/settings.json is intentionally local-only and not tracked in git.
.codex-notify is runtime trigger data and not tracked in git.

License

MIT. See LICENSE.