bark-notify

bark-notify is a lightweight Codex plugin that sends one Bark push notification whenever Codex completes a main-thread turn.

• No third-party Python packages
• No Bark key stored in the plugin or repository
• macOS, Linux, and Windows hook commands
• Self-hosted Bark servers supported
• Conversation content excluded by default
• Notification failures never block Codex
• Installation requires a complete Bark URL before Codex installs the plugin

Install with an agent

Give your coding agent this repository and the following instruction:

Install the bark-notify Codex plugin from this repository.
Run plugins/scripts/install.py and ask me for my complete Bark URL during
installation. It must look like https://api.day.app/YOUR_DEVICE_KEY/.
Do not run codex plugin add before the URL has been validated and saved.
Store the URL only in bark-notify's private user config file with mode 0600;
never write it into the repository, marketplace.json, logs, or shell history.
Run all verification in dry-run mode, then tell me to review and trust the
plugin hook with /hooks in a new Codex session.

The installer must use plugins/scripts/install.py. Codex marketplace metadata cannot collect arbitrary secrets for a hook-only plugin, so running codex plugin add directly bypasses Bark configuration. The bundled installer validates and saves the URL before invoking Codex.

Manual install

Requirements: Codex with plugin lifecycle-hook support, Python 3.9+, and network access to your Bark server.

From the repository root, run the required installer:

python3 plugins/scripts/install.py

Enter a complete Bark URL in this form when prompted:

https://api.day.app/YOUR_DEVICE_KEY/

The prompt does not echo the URL because it contains the device key. An empty URL, a server URL without a key, or a URL containing a query or fragment aborts installation before Codex installs the plugin.

The installer stores the result at:

• macOS/Linux: ${XDG_CONFIG_HOME:-~/.config}/bark-notify/config.json
• Windows: %APPDATA%\bark-notify\config.json

Start a new Codex session, open /hooks, review the bark-notify hook, and trust it. Installed plugin hooks do not run until their exact definition is trusted.

For a GitHub-hosted repository, clone it and run the same installer:

git clone https://github.com/OWNER/bark-notify.git
cd bark-notify
python3 plugins/scripts/install.py

Configuration

The private JSON config uses this shape:

{
  "url": "https://api.day.app/YOUR_DEVICE_KEY/",
  "title": "Codex",
  "group": "Codex",
  "include_message": false
}

Self-hosted Bark URLs use the same format: the final path segment must be the device key. Keep include_message false unless you intentionally want the final Codex response sent through Bark.

Environment variables override the file:

Variable	Purpose
BARK_URL	Complete Bark URL including the device key
BARK_TITLE	Notification title
BARK_GROUP	Bark notification group
BARK_INCLUDE_MESSAGE	Include the final assistant message (true/false)
BARK_TIMEOUT	Network timeout in seconds (clamped to 0.2-4.0)
BARK_NOTIFY_CONFIG	Alternate config file path
BARK_NOTIFY_DRY_RUN	Skip network I/O when true

Verify safely

Plugin structure and manifest:

python3 /path/to/plugin-creator/scripts/validate_plugin.py plugins

Unit tests and a hook smoke test, both without network or user-config writes:

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s plugins/tests
printf '%s' '{"cwd":"/tmp/example","last_assistant_message":"Done"}' | \
  BARK_URL=https://api.day.app/DRY_RUN_KEY/ BARK_NOTIFY_DRY_RUN=true \
  python3 plugins/scripts/bark_notify.py

The smoke test prints {} to stdout and a dry-run note to stderr.

Behavior

The plugin uses Codex's Stop lifecycle event, so it notifies after each completed main-thread turn, not after subagents finish. A notification contains the completion status, project directory, and a short session ID. When include_message is enabled, the compacted final response is appended without replacing this context.

Codex's current Stop hook does not expose the conversation title shown in the UI. The plugin therefore cannot retrieve that title reliably today and does not parse the undocumented transcript format. It accepts session_title, thread_title, thread_name, or title if a future or custom hook runtime supplies one; that value is then included in the Bark title and body. Otherwise, the project name and short session_id are used as the fallback.

A SessionStart hook checks configuration when a Codex session starts. If the URL is missing or invalid, both SessionStart and Stop return a visible systemMessage instead of silently skipping notification.

To notify only when a main thread is closed, change Stop to SessionEnd in plugins/hooks/hooks.json. SessionEnd is a different lifecycle event and may not fire immediately when Codex finishes a task.

Uninstall

codex plugin remove bark-notify@bark-notify
codex plugin marketplace remove bark-notify

The private config is intentionally retained so reinstalling does not require re-entering the key. Remove it separately if you no longer need it.

License

MIT