CODEX NOTIFIER
==============

Codex Notifier sends Windows and Slack alerts when Codex finishes a real task in VS Code.

It filters Codex internal title-generation events, caches the generated title, and uses that
title when the final task-completion event arrives.


FEATURES
--------

- Windows desktop notifications
- Slack DM delivery through a Slack bot token
- Slack webhook fallback
- Local Slack OAuth setup foundation
- Voice announcement
- Beep alert
- Duplicate notification prevention
- Automatic project name detection from the Codex payload cwd
- Local task history
- Debug log
- PyInstaller EXE build script


REQUIREMENTS
------------

- Windows
- Python 3 and the Python launcher: py
- Python packages:
  - winotify
  - requests
  - pyinstaller, only needed for EXE builds


SLACK APP SETUP
---------------

Create a Slack app in api.slack.com/apps.

Required bot scopes:

- chat:write
- im:write

Optional scope:

- incoming-webhook

For local OAuth testing, add this redirect URL to the Slack app:

http://localhost:8765/slack/oauth/callback

Then place the Slack client ID and client secret in:

C:\Users\<YourUser>\.codex\codex-notifier-config.json

OAuth setup can be launched by the installer or manually:

py C:\Users\<YourUser>\.codex\notify.py --slack-oauth-setup


MANUAL TOKEN FALLBACK
---------------------

If OAuth is not ready, paste a Bot User OAuth Token during installer setup.

Slack DM delivery also needs a Slack user ID. The installer only asks for it as an optional
fallback because OAuth may be able to discover it. If DM delivery does not work, add:

"slack_user_id": "UXXXXXXXX"

to codex-notifier-config.json.


INSTALLATION
------------

Open PowerShell as a normal user and run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
C:\CodexNotifier\install-codex-notifier.ps1

The installer:

- Checks Python
- Installs winotify, requests, and pyinstaller
- Creates C:\Users\<YourUser>\.codex
- Backs up existing notifier files
- Copies notify.py and codex-notifier-config.json
- Offers Slack OAuth, manual token, or skip
- Updates C:\Users\<YourUser>\.codex\config.toml
- Runs the test flow

Restart VS Code after installation.


BUILD EXE
---------

Run:

C:\CodexNotifier\build-exe.ps1

The EXE is created at:

C:\CodexNotifier\dist\CodexNotifier.exe

To switch Codex from Python to the EXE, edit:

C:\Users\<YourUser>\.codex\config.toml

Use:

notify = ["C:/CodexNotifier/dist/CodexNotifier.exe"]

[tui]
notifications = ["agent-turn-complete"]


TESTING
-------

Run:

C:\CodexNotifier\test-codex-notifier.ps1

The test sends:

1. Internal title-generation event
   Expected: no notification, title cached.

2. Real completion event
   Expected: notification shown using cached title.

3. Real completion event with cwd C:\CodexNotifier
   Expected project name: CodexNotifier.

4. Manual fallback event
   Expected generic notification.


CONFIGURATION
-------------

Edit:

C:\Users\<YourUser>\.codex\codex-notifier-config.json

Important options:

- project_name: Auto uses the cwd folder name from the Codex payload.
- slack_delivery_mode: bot_dm is the v1.1 target mode.
- duplicate_window_seconds: suppresses repeated identical notifications.
- slack_bot_token: Slack Bot User OAuth Token.
- slack_user_id: Slack user to DM.
- slack_webhook_url: webhook fallback if no bot token is available.

Environment variables are still supported as fallback:

- CODEX_SLACK_BOT_TOKEN
- CODEX_SLACK_USER_ID
- CODEX_SLACK_WEBHOOK

Config file values take priority over environment variables.


LOGS
----

Debug log:

C:\Users\<YourUser>\.codex\notify-debug.log

Task history:

C:\Users\<YourUser>\.codex\codex-task-history.log

Title cache:

C:\Users\<YourUser>\.codex\notify-title-cache.json


TROUBLESHOOTING
---------------

- No Windows notification: confirm notifications are enabled in Windows settings.
- No Slack DM: confirm bot token, user ID, chat:write, and im:write.
- OAuth fails: confirm client ID, client secret, redirect URL, and local port 8765.
- No mobile Slack alert: open the app DM and check Slack mobile notification settings.
- Python not found: install Python and ensure the py launcher is available.
- Duplicate messages missing: check duplicate_window_seconds.
- Wrong project name: ensure Codex sends cwd in the payload or set project_name manually.


SECURITY NOTES
--------------

Do not share bot tokens, client secrets, or webhook URLs.

If a token is exposed, rotate or reinstall the Slack app token immediately.

The notifier does not print or log actual tokens. It only logs whether token-like values exist.


CURRENT LIMITATION
------------------

The v1.1 OAuth support is a local foundation. Proper public OAuth distribution later requires
a production redirect URL and a hosted backend or a published Slack app setup.


UNINSTALL
---------

Run:

C:\CodexNotifier\uninstall-codex-notifier.ps1

The uninstaller removes notifier runtime files but leaves config.toml in place so trusted
project sections are not deleted accidentally.
