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 (quiet status or banner popup).

[!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 notifications.
• 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

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

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.

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.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
• 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-finish-notifier-vscode/
|- .eslintrc.cjs               # ESLint config
|- .github/
|  `- workflows/
|     `- ci.yml                # GitHub Actions CI
|- .gitignore                    # Git exclusions for local/dev artifacts
|- .vscodeignore                 # VSIX packaging exclusions
|- 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
|- package-lock.json             # Locked npm dependency tree
|- package.json                  # VS Code extension manifest/config schema
|- extension.js                  # Core extension runtime (commands + watchers)
|- scripts/
|  |- test-session-events.js     # Unit-style session event checks
|  |- test-vsix.js               # VSIX smoke test
|  `- validate-release.js        # Release validation checks
|- session-events.js             # Session parsing helpers
|- codex-done.ps1                # Helper trigger script for .codex-notify flow
|- notification1.wav             # Bundled default sound (error)
|- notification2.wav             # Bundled default sound (complete)
`- .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.
• codex-notifier-private.vsix is a generated install artifact, not a source file.

License

MIT. See LICENSE.