{"_id":"@aungmyokyaw/opencode-notify","_rev":"3-e89511c73fd153823eaecb981a774caf","name":"@aungmyokyaw/opencode-notify","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.1":{"name":"@aungmyokyaw/opencode-notify","version":"0.1.1","keywords":["opencode","opencode-plugin","notification"],"author":{"name":"aungmyokyaw"},"license":"MIT","_id":"@aungmyokyaw/opencode-notify@0.1.1","maintainers":[{"name":"aungmyokyaw","email":"realAungMyoKyaw@duck.com"}],"dist":{"shasum":"a484f3b305d55f88eaa0187eb1c875d44044df62","tarball":"https://registry.npmjs.org/@aungmyokyaw/opencode-notify/-/opencode-notify-0.1.1.tgz","fileCount":30,"integrity":"sha512-imfxZoOpV2hbqu7hnXUWJ5vORNyEXtkJXKHeVccf/pJN5AroolmuB1ZHdJiEUr5BnR4Gwge4nLbW6B1LxKO/gw==","signatures":[{"sig":"MEYCIQCITKQ2X++zMfI6mrmJxK1Z849oo6Ct5egSK4leBkMRCAIhALGX4Ew7zdPZGZFGDToODPt5FzxBVycLF/ZVq7sEhrKK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20674},"main":"dist/plugin.js","type":"module","types":"dist/plugin.d.ts","gitHead":"48ce54ba6c8650be547ccaab55f4de00932ccc00","scripts":{"lint":"eslint src/ tests/","test":"node --experimental-vm-modules node_modules/.bin/jest","build":"tsc"},"_npmUser":{"name":"aungmyokyaw","email":"realAungMyoKyaw@duck.com"},"_npmVersion":"11.11.1","description":"OpenCode plugin that notifies user when AI request/session completes","directories":{},"_nodeVersion":"25.8.2","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.0","typescript":"^5.4.0","@types/jest":"^29.5.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/opencode-notify_0.1.1_1776621013320_0.15774998079650615","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@aungmyokyaw/opencode-notify","version":"0.1.2","keywords":["opencode","opencode-plugin","notification"],"author":{"name":"aungmyokyaw"},"license":"MIT","_id":"@aungmyokyaw/opencode-notify@0.1.2","maintainers":[{"name":"aungmyokyaw","email":"realAungMyoKyaw@duck.com"}],"dist":{"shasum":"80d47a9dfecc787a629c55be525df658783c49ae","tarball":"https://registry.npmjs.org/@aungmyokyaw/opencode-notify/-/opencode-notify-0.1.2.tgz","fileCount":30,"integrity":"sha512-ne94QvbKPDRKp93jyWjP8srzOEueeJrQ6KK/sLd2myMaoh+xQlHFbL/D5QPO8l+j9Nfm9uQzuPFyEWeNw+4tqg==","signatures":[{"sig":"MEUCIHNxMidQWFrqMqwUpfAEju8SauUuTW60KyOwCSPftowgAiEA3RsGUoid83rGJjhj2TKtZ3//d6PH70Vl0NisP5lhNR0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20674},"main":"dist/plugin.js","type":"module","types":"dist/plugin.d.ts","gitHead":"3d86ed54c0a09e3b26dadf7c279549dca38b6857","scripts":{"lint":"eslint src/ tests/","test":"node --experimental-vm-modules node_modules/.bin/jest","build":"tsc"},"_npmUser":{"name":"aungmyokyaw","email":"realAungMyoKyaw@duck.com"},"_npmVersion":"10.8.2","description":"OpenCode plugin that notifies user when AI request/session completes","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.0","typescript":"^5.4.0","@types/jest":"^29.5.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/opencode-notify_0.1.2_1776621055214_0.3986778448173127","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@aungmyokyaw/opencode-notify","version":"0.1.3","description":"OpenCode plugin that notifies user when AI request/session completes","main":"dist/plugin.js","types":"dist/plugin.d.ts","type":"module","scripts":{"build":"tsc","test":"node --experimental-vm-modules node_modules/.bin/jest","lint":"eslint src/ tests/"},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","jest":"^29.7.0","ts-jest":"^29.1.0","typescript":"^5.4.0"},"keywords":["opencode","opencode-plugin","notification"],"author":{"name":"aungmyokyaw"},"license":"MIT","_id":"@aungmyokyaw/opencode-notify@0.1.3","gitHead":"1814dcdc0afa3e8ddfb4df2f0cef1db9e00b1096","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-NyCEukuZFvUwAPnsiKt+3+kUeVpCYbrza6Vrqc6zVbw9GTr1jHdNnGCfsTWPYv2sS99AYTptGmi37ocfqTAD7A==","shasum":"c1e68902589721c6f3acb3a53f07c71999162ce1","tarball":"https://registry.npmjs.org/@aungmyokyaw/opencode-notify/-/opencode-notify-0.1.3.tgz","fileCount":30,"unpackedSize":26503,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG1zBEum/Pik9VUZ7OEHNu5a4TszNmMZEpfLgTZsFr59AiEA/nDMcqTyeQjN7H9CCexvsxh/wWdVBQTPZdzxSfZviYw="}]},"_npmUser":{"name":"aungmyokyaw","email":"realAungMyoKyaw@duck.com"},"directories":{},"maintainers":[{"name":"aungmyokyaw","email":"realAungMyoKyaw@duck.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/opencode-notify_0.1.3_1776621393992_0.28091252815805756"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-19T17:50:13.249Z","modified":"2026-04-19T17:56:34.228Z","0.1.1":"2026-04-19T17:50:13.447Z","0.1.2":"2026-04-19T17:50:55.406Z","0.1.3":"2026-04-19T17:56:34.129Z"},"author":{"name":"aungmyokyaw"},"license":"MIT","keywords":["opencode","opencode-plugin","notification"],"description":"OpenCode plugin that notifies user when AI request/session completes","maintainers":[{"name":"aungmyokyaw","email":"realAungMyoKyaw@duck.com"}],"readme":"# @aungmyokyaw/opencode-notify\n\n[![npm version](https://img.shields.io/npm/v/@aungmyokyaw/opencode-notify.svg)](https://www.npmjs.com/package/@aungmyokyaw/opencode-notify)\n[![CI](https://github.com/AungMyoKyaw/opencode-notify/actions/workflows/ci.yml/badge.svg)](https://github.com/AungMyoKyaw/opencode-notify/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n> Get notified when OpenCode AI sessions complete. Zero-config defaults, multi-platform support, and webhook integration.\n\n## Quick Start\n\nAdd to your `opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugin\": [\"@aungmyokyaw/opencode-notify\"]\n}\n```\n\nDone. OpenCode installs and loads the plugin automatically. You'll get a terminal bell on every session completion.\n\n---\n\n## Install\n\n### Via npm (recommended)\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugin\": [\"@aungmyokyaw/opencode-notify\"]\n}\n```\n\nOpenCode installs npm plugins automatically at startup using Bun.\n\n### From local files\n\nClone or download this repo, then point to the built file:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugin\": [\"file:///absolute/path/to/opencode-notify/dist/plugin.js\"]\n}\n```\n\nOr copy `dist/plugin.js` into your plugin directory:\n- Project-level: `.opencode/plugins/`\n- Global: `~/.config/opencode/plugins/`\n\n---\n\n## Why This Plugin?\n\n| Feature | `@aungmyokyaw/opencode-notify` | `opencode-notification` | `@goodnesshq/opencode-notification` |\n|---------|-------------------------------|-------------------------|-------------------------------------|\n| Install method | npm auto-install | npm auto-install | `npx setup` required |\n| macOS notifications | ✅ | ✅ | ✅ |\n| Terminal bell | ✅ | ✅ | ❌ |\n| TUI popup | ✅ | ❌ | ❌ |\n| Custom webhook | ✅ | ❌ | ❌ |\n| Config location | `opencode.json` | `opencode.json` | External JSON file |\n| Zero-config default | ✅ | ❌ | ❌ |\n| Events supported | `session.idle` | 3 events | 3+ events |\n\n**Best for:** Users who want simple, configurable notifications without external setup commands or config files.\n\n---\n\n## Config\n\nAdd a `plugin-notify` block to `opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugin\": [\"@aungmyokyaw/opencode-notify\"],\n  \"plugin-notify\": {\n    \"enabled\": true,\n    \"notifiers\": [\"macos\", \"bell\"],\n    \"macos\": { \"sound\": \"default\" },\n    \"bell\": { \"count\": 1 },\n    \"tui\": { \"durationMs\": 5000 },\n    \"webhook\": {\n      \"url\": \"https://hooks.slack.com/...\",\n      \"method\": \"POST\",\n      \"headers\": {}\n    },\n    \"dnd\": false,\n    \"focusAware\": false\n  }\n}\n```\n\n### Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `enabled` | `boolean` | `true` | Turn notifications on/off |\n| `notifiers` | `string[]` | `[]` | List of notifiers to use |\n| `dnd` | `boolean` | `false` | Do-not-disturb mode (silences all) |\n| `focusAware` | `boolean` | `false` | Skip notifications when OpenCode has focus |\n| `macos.sound` | `string` | — | macOS alert sound name |\n| `bell.count` | `number` | `1` | Number of bell characters |\n| `tui.durationMs` | `number` | `5000` | How long TUI popup stays visible |\n| `webhook.url` | `string` | — | POST destination URL |\n| `webhook.method` | `string` | `POST` | HTTP method |\n| `webhook.headers` | `object` | `{}` | Extra request headers |\n\n---\n\n## Notifiers\n\n### `macos`\n\nNative macOS notification via `osascript`.\n\n```json\n{\n  \"plugin-notify\": {\n    \"notifiers\": [\"macos\"],\n    \"macos\": { \"sound\": \"Purr\" }\n  }\n}\n```\n\n**Requirements:** macOS with `osascript` available.\n\n### `bell`\n\nTerminal bell character (`\\u0007`). Works on every platform.\n\n```json\n{\n  \"plugin-notify\": {\n    \"notifiers\": [\"bell\"],\n    \"bell\": { \"count\": 3 }\n  }\n}\n```\n\n### `tui`\n\nBoxed popup drawn directly in the terminal.\n\n```json\n{\n  \"plugin-notify\": {\n    \"notifiers\": [\"tui\"],\n    \"tui\": { \"durationMs\": 3000 }\n  }\n}\n```\n\nOutput looks like:\n\n```\n┌─────────────────────────────┐\n│  Session Complete: My Task  │\n│  Summary: Done              │\n└─────────────────────────────┘\n```\n\n### `webhook`\n\nPOST JSON payload to any URL.\n\n```json\n{\n  \"plugin-notify\": {\n    \"notifiers\": [\"webhook\"],\n    \"webhook\": {\n      \"url\": \"https://hooks.slack.com/services/...\",\n      \"method\": \"POST\",\n      \"headers\": { \"Authorization\": \"Bearer xxx\" }\n    }\n  }\n}\n```\n\nPayload shape:\n\n```json\n{\n  \"event\": \"session.idle\",\n  \"title\": \"OpenCode\",\n  \"summary\": \"Session complete\",\n  \"timestamp\": \"2026-04-20T00:00:00.000Z\"\n}\n```\n\n---\n\n## Events\n\nThe plugin listens for OpenCode events and dispatches notifications.\n\n| Event | When it fires | Default action |\n|-------|--------------|----------------|\n| `session.idle` | AI finishes responding | ✅ Notify |\n| `session.error` | Session encounters an error | ❌ (not yet) |\n| `permission.asked` | LLM needs your permission | ❌ (not yet) |\n\n> **Note:** Currently only `session.idle` is implemented. `session.error` and `permission.asked` are planned for v0.2.0.\n\n---\n\n## How It Works\n\n1. OpenCode fires `session.idle` when the AI stops generating.\n2. Plugin checks `enabled` and `dnd` flags.\n3. If `focusAware` is on and OpenCode has terminal focus, skip.\n4. Build `NotifyPayload` from event data.\n5. Dispatch to every notifier in the `notifiers` array.\n6. Each notifier runs independently. Failures are logged to stderr but never block the session.\n\n---\n\n## Troubleshooting\n\n### macOS notifications not showing\n\n- Verify `osascript` is in your PATH: `which osascript`\n- Check macOS Notification Center settings for \"Script Editor\"\n- Try a manual test: `osascript -e 'display notification \"test\"'`\n\n### Webhook not firing\n\n- Verify `url` is set in config\n- Check network connectivity: `curl -I your-webhook-url`\n- Look for `Webhook URL not configured` or `Webhook failed` in OpenCode output\n\n### Plugin not loading\n\n- Verify plugin is in `opencode.json` `plugin` array\n- Check OpenCode startup logs for install errors\n- Try local file path instead of npm name to rule out registry issues\n\n### Too many notifications\n\n- Enable `dnd: true` for focused work sessions\n- Enable `focusAware: true` to skip when OpenCode is active\n- Reduce `bell.count` to `1`\n\n---\n\n## Contributing\n\nPRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}