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 with safer burst checks.
• 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

1. Open Extensions view in VS Code (Ctrl+Shift+X).
2. Search Esamtrade Codex Notifier.
3. 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

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 response completion notification.

How It Works

1. On activation, the extension starts auto-detection watchers (Codex log/chat) 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 watches Codex stream activity and waits for a real end-state signal, so opening or closing chat should not fire by itself.

Recommended Settings

{
  "codexNotifier.enableSound": true,
  "codexNotifier.enablePopup": true,
  "codexNotifier.completionUseBanner": false,
  "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
• 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.