PourNotify

Local-first desktop, sound, Bark, and History notifications for Codex.

Download • Releases • Documentation • Source Code

What's new in v1.0.4

• Introduces the new Pour UI paper-airplane application icon.
• Adds optional Windows login startup that runs silently without opening or flashing the main window.
• Prevents duplicate startup launches from creating a second resident, while a normal manual launch still opens the existing application window.
• Preserves compatibility with existing Codex, IPC, Bark, desktop, sound, History, and Diagnostics behavior.

Overview

PourNotify receives Codex completion events and routes them through the channels enabled for each category. Notification Test uses the same dispatcher as real Codex completions.

Configuration, History, and diagnostics stay on your computer. PourNotify has no hosted backend or account requirement.

Features

Desktop Notifications Native banners and Notification Center entries.	Bark Delivery HTTPS pushes through your configured Bark server.
Notification History Search, copy, inspect, and export local records.	Quiet Hours Control interruptions with critical-event exceptions.
IPC Single-resident routing for Codex and second-process events.	Diagnostics Rotating JSONL logs with Bark credentials redacted.
Custom Sounds Choose sound and volume independently by category.	Background Startup Start silently at login and remain available in the tray.

Download

The latest stable release is v1.0.4.

• Windows: download PourNotify-v1.0.4-Windows.exe.
• All releases: visit GitHub Releases.
• The automatically generated source archives are source code, not the normal Windows executable.
• Windows and macOS builds pass in CI. Physical macOS runtime validation is still pending, and the v1.0.4 release currently publishes only the Windows executable.

Quick start

1. Download and launch the latest Windows release.
2. Configure desktop, sound, History, and optional Bark delivery in Settings.
3. Optionally enable Start PourNotify automatically when I sign in for silent tray startup.
4. Connect the global Codex notification hook using the example below.
5. Run Notification Test, then complete a Codex task to verify delivery.

When PourNotify is already running, launching it normally opens the existing window. Login startup does not open the window or create a second resident.

The packaged Windows application does not require a separate Python installation.

Codex integration

PourNotify accepts one CLI argument: --notify <Codex JSON payload>. A stable installation path is important because Codex invokes that executable after every supported event.

If Codex already uses the codex-computer-use turn-ended wrapper, keep the wrapper and set PourNotify as its previous notification command. In the global Codex config.toml, preserve the existing wrapper path and use this structure:

notify = [
  "<CODEX_COMPUTER_USE_PATH>",
  "turn-ended",
  "--previous-notify",
  "[\"<POURNOTIFY_INSTALL_PATH>\\\\PourNotify.exe\",\"--notify\"]",
]

Replace both placeholders with stable local paths. On Windows, a suitable PourNotify location is under %LOCALAPPDATA%\Programs\PourNotify; do not point the hook at a project's temporary dist directory.

The wrapper preserves Codex's existing turn-completion handling and forwards the payload to PourNotify. Keep Bark configured inside PourNotify rather than adding a second independent Bark notification script, which would duplicate deliveries.

When PourNotify is already resident, the temporary invocation sends the JSON payload to it through local Qt IPC and exits. If no resident process accepts the connection, the invocation starts a hidden temporary instance, processes the same payload locally, and exits after delivery.

PourNotify currently parses Codex agent-turn-complete hook events. Other payload types are recorded as unsupported diagnostics rather than presented as supported external notifications.

Notification controls

Each notification category keeps its own settings for:

• enabled state;
• desktop, Bark, sound, and History delivery;
• selected sound and volume;
• priority.

Global settings add quiet hours, Bark silence during quiet hours, critical-event exceptions, cooldowns, per-minute limits, and duplicate suppression or merging. The current application ships with 13 configurable categories; the names are intentionally left to the UI because they are application configuration rather than a promised public API.

History and diagnostics

History is stored locally and can be searched, copied, cleared, or exported as JSON or CSV. It preserves the complete notification message while the desktop and Bark presentation may use a shorter delivery preview.

Help > Open Notification Diagnostics opens the local diagnostics directory. Each received hook event produces a JSONL record containing its source, dispatch status, channel attempts and results, HTTP status, duration, and any exception. Logs rotate automatically and never include the configured Bark device key.

Privacy

• PourNotify has no hosted backend, user account, telemetry, or browser cookies.
• Configuration, notification History, and diagnostic logs remain in the local application-data directory unless you explicitly export History.
• PourNotify does not collect or store full Codex conversations. It does store the notification content supplied by the Codex hook in local History, and diagnostics retain the received event payload for troubleshooting.
• Bark delivery sends the notification title and body to the HTTPS Bark server you configure.
• The Bark device key is stored in local configuration. Never commit that file or paste the key into issues, logs, screenshots, or examples.
• Bark responses are redacted before diagnostics are written, and automated coverage verifies that the device key is absent from diagnostic records.

Development

PourNotify requires Python 3.11 or newer for source development.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Run the application from source:

python -m pournotify

Run the repository checks:

python -m ruff check .
python -m pytest

Create a clean PyInstaller build (the script runs the full test suite first):

powershell -ExecutionPolicy Bypass -File .\scripts\build.ps1

Build output is written to dist/. The same test, Ruff, and PyInstaller commands run on windows-latest and macos-latest in GitHub Actions.

Project status

• Latest stable release: v1.0.4
• Windows runtime validation: complete
• Silent Windows login startup and single-resident behavior: validated
• Windows toast, Notification Center retention, sound, Bark, History, Diagnostics, and IPC: validated
• Windows and macOS CI jobs: passing
• Physical macOS runtime validation: pending

Contributing

1. Fork the repository.
2. Create a focused branch for the change.
3. Keep the diff scoped and add or update meaningful tests when behavior changes.
4. Run Ruff and the full pytest suite.
5. Open a pull request describing the change and its validation.

License

PourNotify is available under the MIT License.