Codex notification

Desktop and editor alerts for Codex in Antigravity / VS Code, scoped to the current workspace.

Install and configure

1. Install version 0.2.0 using Extensions → Install from VSIX, or update from your registry. Reload the editor.
2. Run Codex notification: Enable Task Signals in This Workspace. This appends a short, idempotent status-reporting section to AGENTS.md, preserving existing instructions. Start a new Codex chat so it loads the instructions.
3. Run Codex notification: Choose Notification Mode: questions only, completed tasks only, or both.
4. Run Codex notification: Test Notification. For native macOS alerts, enable notifications and sound for terminal-notifier in System Settings. Windows may show SnoreToast. Linux requires notify-send.

Accurate event handling

Ordinary Codex turn endings do not produce completion notifications. Subagents, CLI sessions, and sessions outside the current workspace are ignored. Interrupted work, pending questions, new user input, and continued turns cancel candidate completion alerts.

Structured synchronous question prompts are tracked until their matching answer. Async prompts must first be accepted; a subsequent user message clears them. A short settling window suppresses questions already answered or canceled before delivery. Explicit waiting-for-input signals also support ordinary prose questions.

Task completion requires Codex to explicitly declare that the entire task is complete, relevant checks have passed, and no required work, approval, clarification, deployment or external verification remains pending. It is a declaration by the agent, not independent verification of success. Without workspace task signals, completion alerts stay silent. Enable them only in workspaces where you want this behavior.

The workspace instructions use hidden Markdown comments on their own line:

<!-- codex-notification:question -->
<!-- codex-notification:task-complete -->

These are recognized only in the final task-complete record and outside code fences. Question signals take precedence over completion signals. A plain task_complete record with no signal is ignored.

Settings

Click the status-bar bell to pause/resume. Open Codex opens the official Codex sidebar; it does not select a particular chat. Multiple main chats in the same workspace may each produce relevant alerts. Empty editor windows produce no session alerts. Remote-host records must be available locally to be monitored.

Privacy and compatibility

The extension reads local sessions/**/rollout-*.jsonl incrementally. It retains only local file offsets, bounded partial-record buffers, boolean eligibility, pending-question metadata, and hashed deduplication keys. Notifications use fixed generic text; no prompts, responses, account details, paths, or session IDs are exposed. It does not read auth files, send network requests, install hooks, approve actions, or transmit telemetry.

The rollout schema is not a stable public API; detection must be rechecked after Codex changes. Questions that provide neither a supported structured prompt nor the explicit waiting-for-input signal are not detected. Already issued OS alerts cannot be retracted if a question is answered later.

Native helpers are distributed through node-notifier with network fallbacks disabled. The macOS helper is a universal build from unmodified terminal-notifier 3.1.0 source; provenance and licenses are in vendor/. Desktop delivery depends on OS permissions and Focus/Do Not Disturb. Windows/Linux delivery needs separate platform testing.

Development

Run npm ci --ignore-scripts, npm test, then npx --yes @vscode/vsce package. Build the generated macOS helper as described in vendor/README.md before packaging from a clean checkout. Never bundle conversation records or workspace AGENTS.md files.

MIT. Independent project; not affiliated with or endorsed by OpenAI.