@erica-s/ai-agent-notify 2.1.5

package/.published

@@ -0,0 +1 @@
+{"version":"2.1.5","date":"2026-03-31T17:50:50.044Z"}

package/README.md

@@ -0,0 +1,100 @@
+# ai-agent-notify
+
+Windows Toast notifications for Claude Code and Codex.
+
+Get notified when Claude or Codex finishes a task, or when Codex requests
+approval.
+
+## Problem It Solves
+
+Claude Code sessions can run for a long time. Once you switch to other windows,
+it becomes easy to miss state changes in the original terminal. This package
+solves two core problems:
+
+### 1. Reminder
+
+- Native Windows Toast notifications
+- Taskbar flashing
+
+### 2. Return To The Session
+
+- Notification titles make the source and result easy to identify
+- The matching terminal window flashes as a visual cue
+- The notification provides an `Open` button that activates the target window
+
+## Install
+
+```bash
+# Recommended: global install via volta or npm
+volta install @erica-s/ai-agent-notify
+# or
+npm install -g @erica-s/ai-agent-notify
+```
+
+## Claude Code
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+    "hooks": {
+        "Stop": [{ "hooks": [{ "type": "command", "command": "ai-agent-notify", "async": true }] }],
+        "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "ai-agent-notify", "async": true }] }]
+    }
+}
+```
+
+- Prefer a global install. `npx --yes @erica-s/ai-agent-notify` is less
+  reliable in async hooks.
+- The click-to-activate protocol is registered automatically on install.
+
+## Codex
+
+Recommended `~/.codex/config.toml`:
+
+```toml
+notify = ["ai-agent-notify"]
+
+[mcp_servers.ai_agent_notify_sidecar]
+command = "cmd.exe"
+args = ["/d", "/c", "ai-agent-notify", "codex-mcp-sidecar"]
+required = false
+startup_timeout_sec = 5
+```
+
+- `notify = ["ai-agent-notify"]` covers completion events such as
+  `agent-turn-complete`.
+- `codex-session-watch` is the main path for approval reminders.
+- `codex-mcp-sidecar` will usually auto-start `codex-session-watch`.
+- Do **not** set `cwd` on the MCP server entry above.
+- After changing Codex `notify`, restart Codex and retest in a fresh TUI
+  session.
+- Prefer a global install. `npx.cmd @erica-s/ai-agent-notify` is less reliable on Windows.
+
+If you are not using the MCP sidecar, start the watcher yourself:
+
+```bash
+ai-agent-notify codex-session-watch
+```
+
+Optional flags:
+
+- `--sessions-dir <path>`: override the Codex sessions directory
+- `--tui-log <path>`: override the Codex TUI log path
+- `--poll-ms <ms>`: change the polling interval
+
+## Requirements
+
+- Windows 10 / 11
+- Node.js >= 16
+- PowerShell 5.1+
+
+## Known Limitations
+
+- **Toast source** shows as "Windows PowerShell" instead of "Claude Code"
+- **Windows 10:** `Open` may not work due to OS limitations
+- **macOS / Linux:** not supported
+
+## License
+
+MIT