feat: v0.2.0 - env var config, comprehensive tests, README rewrite

Implementation:
- OPENCODE_BELL_EVENTS: filter which events trigger the bell
- OPENCODE_BELL_DEBOUNCE: customize debounce window
- Unified debounce key format (event.type:sessionId)
- ring(key, now) with injectable timestamp for testing

Tests (11 cases):
- Env var config filtering, custom debounce, invalid fallback
- Debounce window suppression, expiry, key isolation
- TTY guard for true/false/undefined

Docs:
- README with features list, config section, events table, GIF placeholder
- CLAUDE.md updated with env var config reference

Author: Astro-Han

CLAUDE.md

@@ -0,0 +1,40 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+opencode-bell 是 OpenCode CLI 的终端铃声通知插件。监听 4 种事件（`permission.asked`、`question.asked`、`session.idle`、`session.error`），通过输出 BEL 字符（`\x07`）实现通知。零依赖、单文件实现。
+
+隐私设计：不读取消息内容、不执行外部命令、无网络调用，仅在 TTY 终端输出铃声。
+
+## Commands
+
+```bash
+npm test                        # 运行测试（node:test 原生框架）
+node -e "import('./index.js')"  # 烟雾测试：验证模块可导入
+```
+
+无构建步骤，纯 JS ES Module 直接发布。
+
+## Architecture
+
+`index.js` 导出 `OpencodeBellPlugin` 异步工厂函数，返回 `{ event(e) }` 插件对象。核心机制：
+
+- **会话级防抖**：以 `eventType:sessionId` 为 key，默认 1200ms 内同 key 最多响铃一次
+- **TTY 守卫**：`process.stdout.isTTY` 为 false 时静默跳过
+
+### 环境变量配置
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `OPENCODE_BELL_EVENTS` | 逗号分隔的监听事件列表 | `permission.asked,question.asked,session.idle,session.error` |
+| `OPENCODE_BELL_DEBOUNCE` | 防抖窗口，单位毫秒 | `1200` |
+
+### 测试辅助
+
+插件对象同时暴露 `_ring(key, now)` 方法，供测试直接注入时间戳验证防抖逻辑，生产使用中忽略即可。
+
+## Publishing
+
+`package.json` 的 `files` 字段限制发布为 3 个文件：`index.js`、`README.md`、`LICENSE`。用户通过在 `~/.config/opencode/opencode.json` 添加 `"plugin": ["opencode-bell@版本"]` 安装。

README.md

@@ -1,45 +1,68 @@
 # opencode-bell
 
-OpenCode plugin that triggers a terminal bell on key events.
+<!-- TODO: replace with actual recording -->
+<p align="center"><img src="./docs/demo.gif" alt="opencode-bell demo" width="600"></p>
 
-Privacy-friendly by design: no system notifications, no message content, no external commands, no network calls. It only writes the BEL control character (`\x07`) to stdout.
+Never miss an OpenCode prompt again.
 
-## Install (recommended: npm)
+- Zero dependencies — single-file plugin
+- Privacy-friendly — no message content, no external commands, no network calls
+- Configurable — choose which events trigger the bell
+- Smart debounce — avoids bell spam for the same event type per session
 
-1. Add the plugin to `~/.config/opencode/opencode.json`:
+## Install
+
+### npm (recommended)
+
+Add the plugin to `~/.config/opencode/opencode.json`:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-bell@0.1.1"]
+  "plugin": ["opencode-bell@0.2.0"]
 }
 ```
 
-2. Restart OpenCode CLI.
-
-OpenCode will auto-install the package and cache it under `~/.cache/opencode/node_modules/`.
+Restart OpenCode. It will auto-install the package and cache it under `~/.cache/opencode/node_modules/`.
 
-## Install (local file)
+### Local file
 
 Copy `index.js` into `~/.config/opencode/plugins/` and restart OpenCode.
 
-## What it does
+## Configuration
+
+Two environment variables control behavior:
+
+| Variable | Default | Description |
+|---|---|---|
+| `OPENCODE_BELL_EVENTS` | `permission.asked,question.asked,session.idle,session.error` | Comma-separated list of events that trigger the bell |
+| `OPENCODE_BELL_DEBOUNCE` | `1200` | Minimum ms between repeated bells for the same event type and session. Must be >= 1; 0 or negative falls back to default |
+
+Example — bell only on permission requests, with a 5-second debounce:
+
+```sh
+export OPENCODE_BELL_EVENTS="permission.asked"
+export OPENCODE_BELL_DEBOUNCE="5000"
+```
+
+## Supported Events
 
-The plugin triggers a terminal bell for these events:
+| Event | Fires when |
+|---|---|
+| `permission.asked` | OpenCode needs approval to run a tool |
+| `question.asked` | OpenCode asks the user a question |
+| `session.idle` | A session completes and is waiting for input |
+| `session.error` | A session encounters an error |
 
-- `permission.asked`
-- `question.asked`
-- `session.idle`
-- `session.error`
+## How it works
 
-## Verify
+The plugin writes the BEL character (`\x07`) to stdout. Your terminal emulator interprets it — typically as an audio beep, a visual flash, or a dock badge, depending on your terminal settings.
 
-- Trigger a permission request (e.g., any tool that requires approval).
-- Or wait for a session to complete (`session.idle`).
+## Troubleshooting
 
-If you do not hear/see anything, check Terminal.app settings:
+No sound or flash? Check your terminal bell settings:
 
-- Terminal.app -> Settings -> Profiles -> Bell
+- **Terminal.app**: Settings -> Profiles -> Bell
 
 ## Uninstall
 

index.js

@@ -1,12 +1,32 @@
+// Event types that trigger the bell, comma-separated. Defaults to all four.
+const DEFAULT_EVENTS = "permission.asked,question.asked,session.idle,session.error"
+// Empty string or whitespace-only also falls back to defaults
+const rawEvents = process.env.OPENCODE_BELL_EVENTS || DEFAULT_EVENTS
+const parsed = rawEvents.split(",").map((s) => s.trim()).filter(Boolean)
+const ENABLED_EVENTS = new Set(parsed.length > 0 ? parsed : DEFAULT_EVENTS.split(","))
+
+// Debounce window in ms. Falls back to 1200 if NaN, negative, or zero.
+const parsedDebounce = parseInt(process.env.OPENCODE_BELL_DEBOUNCE, 10)
+const DEBOUNCE_MS = parsedDebounce > 0 ? parsedDebounce : 1200
+
+/**
+ * OpencodeBellPlugin — OpenCode plugin factory.
+ * Listens for configured events and writes ASCII BEL to the terminal.
+ * Same key only rings once within the debounce window.
+ */
 export const OpencodeBellPlugin = async () => {
   const bell = "\x07"
-  const debounceMs = 1200
+  // Map<key, lastRingTimestamp> — tracks last ring time per key
   const last = new Map()
 
-  const ring = (key) => {
-    const now = Date.now()
+  /**
+   * ring — debounced bell for a given key.
+   * @param {string} key - debounce key, format "event.type:sessionId" or "event.type"
+   * @param {number} now - current timestamp in ms, injectable for testing
+   */
+  const ring = (key, now = Date.now()) => {
     const prev = last.get(key) || 0
-    if (now - prev < debounceMs) return
+    if (now - prev < DEBOUNCE_MS) return
     last.set(key, now)
     if (process.stdout && process.stdout.isTTY) {
       process.stdout.write(bell)
@@ -15,22 +35,14 @@ export const OpencodeBellPlugin = async () => {
 
   return {
     event: async ({ event }) => {
-      if (event?.type === "permission.asked") {
-        const sessionId = event?.properties?.sessionID
-        ring(sessionId ? `permission:${sessionId}` : "permission")
-      }
-      if (event?.type === "question.asked") {
-        const sessionId = event?.properties?.sessionID
-        ring(sessionId ? `question:${sessionId}` : "question")
-      }
-      if (event?.type === "session.idle") {
-        const sessionId = event?.properties?.sessionID
-        ring(sessionId ? `idle:${sessionId}` : "idle")
-      }
-      if (event?.type === "session.error") {
-        const sessionId = event?.properties?.sessionID
-        ring(sessionId ? `error:${sessionId}` : "error")
-      }
-    }
+      // Only handle events in the configured set, silently skip the rest
+      if (!ENABLED_EVENTS.has(event?.type)) return
+      const sessionId = event?.properties?.sessionID
+      // Use "type:id" when sessionId exists, plain "type" when missing (no trailing colon)
+      const key = sessionId ? `${event.type}:${sessionId}` : event.type
+      ring(key)
+    },
+    // Exposed for testing
+    _ring: ring,
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-bell",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenCode plugin: privacy-friendly terminal bell notifications",
   "license": "MIT",
   "type": "module",