@xwss/agentbell 0.1.0

package/README.md

@@ -0,0 +1,969 @@
+# AgentBell
+
+AgentBell: get notified when your AI coding agent finishes.
+
+AgentBell 閺勵垯绔存稉顏囨硶楠炲啿褰?CLI 瀹搞儱鍙块敍宀€鏁ゆ禍搴℃躬 Claude Code閵嗕竼odex閵嗕箓S Code Copilot Agent 缁?AI coding agent 鐎瑰本鍨氭禒璇插閵嗕礁浠犲銏ｇ箥鐞涘被鈧胶鐡戝鍛扮翻閸忋儲鍨ㄩ棁鈧憰浣规綀闂勬劖妞傞敍宀冨殰閸斻劌鎮滈幍瀣簚閸欐垿鈧焦褰侀柋鎺嬧偓?
+缁楊兛绔撮悧鍫滅喘閸忓牊鏁幐?ntfy閵嗗倸褰傞柅浣侯伂閸欘亪娓剁憰浣藉厴鐠佸潡妫舵径鏍秹楠炶泛褰傞崙?HTTP 鐠囬攱鐪伴敍宀勨偓鍌氭値閺堫剙婀撮悽浣冨壋閵嗕浇绻欑粙?SSH閵嗕箘SL閵嗕笍ev Container閵嗕浇绻欓幒褏鏁搁懘鎴犵搼閸︾儤娅欓妴?
+## Why Not Bluetooth
+
+AgentBell 娑撳秴浠涢拑婵堝閻╃绻涢幍瀣箚閵嗗倽鎽戦悧娆戞纯鏉╃偤娓剁憰浣割槱閻炲棝鍘ょ€靛箍鈧胶閮寸紒鐔告綀闂勬劑鈧礁宸堕崯鍡楀礂鐠侇喓鈧礁鎮楅崣棰佺箽濞茶鎷扮捄銊ラ挬閸欐澘妯婂鍌︾礉閸欘垶娼幀褍绶㈤梾鍙ョ箽鐠囦降鈧?
+閹恒劏宕橀柧鎹愮熅閺勵垽绱?
+1. AI coding hook 閸︺劌鐤勯梽鍛扮箥鐞?agent 閻ㄥ嫭婧€閸ｃ劋绗傞幍褑顢戦妴?2. AgentBell 闁俺绻?HTTP 閹跺﹪鈧氨鐓￠崣鎴濆煂 ntfy閵?3. 鐎瑰宕滈幍瀣簚閺€璺哄煂 ntfy 闁氨鐓￠妴?4. 缁崵绮洪崪灞惧閻?App 鐠愮喕鐭楅幎濠団偓姘辩叀鏉烆剙褰傞崚鐗堝閻滎垬鈧?
+鏉╂瑦鐗辨潻婊呪柤閺堝搫娅掗崣顏囶洣閸欘垯浜掔拋鍧楁６ ntfy server閿涘苯姘ㄩ懗鑺ュ絹闁辨帊缍橀惃鍕閺堟亽鈧?
+## Android Setup
+
+1. 鐎瑰顥?ntfy Android閵?2. 鐠併垽妲勬稉鈧稉顏堟閺堟亽鈧椒绗夐崣顖滃閻?topic閵?3. 閸忎浇顔?ntfy 閻ㄥ嫰鈧氨鐓￠弶鍐閵?4. 閸忔娊妫?ntfy 閻ㄥ嫮鏁稿Ч鐘辩喘閸栨牠妾洪崚韬测偓?5. 閸︺劍澧滈悳?App 娑擃厼鍘戠拋姝屾祮閸?ntfy 閻ㄥ嫰鈧氨鐓￠妴?
+婵″倹鐏夋担璺ㄦ暏 `https://ntfy.sh` 閸忣剙鍙￠張宥呭閿涘矁顕幎?topic 瑜版挷缍?bearer secret閵嗗倻鐓￠柆?topic 閻ㄥ嫪姹夐柅姘埗鐏忚精鍏橀崥鎴ｎ嚉 topic 閸欐垶绉烽幁顖涘灗鐠併垽妲勫☉鍫熶紖閿涘本澧嶆禒銉ょ瑝鐟曚椒濞囬悽銊ヮ潣閸氬秲鈧線銆嶉惄顔兼倳閵嗕線鍋栫粻渚库偓浣稿彆閸欑鎮曟潻娆戣閸欘垳瀵?topic閵?
+## Installation
+
+Install AgentBell from npm:
+
+```bash
+npm install -g @xwss/agentbell
+agentbell setup
+```
+
+Although the npm package is scoped as `@xwss/agentbell`, the installed CLI command is still `agentbell`.
+
+For beta builds:
+
+```bash
+npm install -g @xwss/agentbell@beta
+```
+
+AgentBell requires Node.js 20 or newer.
+
+## Development Install
+
+For local development:
+
+```bash
+git clone <your-agentbell-repo-url>
+cd AgentBell
+npm install
+npm run build
+node dist/cli.js setup
+```
+
+## Local Package Test
+
+Before publishing, test the npm package locally:
+
+```bash
+npm run build
+npm pack
+npm install -g ./xwss-agentbell-0.1.0.tgz
+agentbell --help
+agentbell setup --dry-run --yes --targets none --no-test
+```
+
+## Uninstall
+
+```bash
+npm uninstall -g @xwss/agentbell
+```
+## Quick Start
+
+```bash
+npm install -g @xwss/agentbell
+agentbell setup
+```
+
+閺堫剙婀村鈧崣鎴ｇ箥鐞涘矉绱?
+```bash
+npm install
+npm run build
+npm test
+npm run dev -- test
+```
+
+## Setup Wizard
+
+`agentbell setup` is the recommended first command on a new machine. It is a guided setup flow that:
+
+- generates a random ntfy topic
+- writes `~/.agentbell/config.json`
+- asks for a machine display name
+- guides Android ntfy subscription
+- sends a setup test notification
+- installs selected AI coding hooks
+
+Examples:
+
+```bash
+agentbell setup
+agentbell setup --yes --targets none --no-test
+agentbell setup --targets codex,claude-code
+agentbell setup --dry-run
+```
+
+Useful options:
+
+- `--config <path>` writes a specific config file.
+- `--topic <topic>` uses a specific ntfy topic.
+- `--machine-name <name>` sets the display name used in notifications.
+- `--server <url>` sets the ntfy server.
+- `--targets <targets>` accepts `all`, `none`, or comma-separated `codex,claude-code,vscode-agent`.
+- `--yes` uses defaults for prompts.
+- `--no-test` skips the phone test notification.
+- `--dry-run` previews setup without writing files, sending notifications, or installing hooks.
+
+## Topic and Machine Name
+
+The ntfy topic is a secret transport address, not a display name. Anyone who knows the topic can usually publish to it, so use a long random topic and do not commit it to a public repository.
+
+The machine display name is safe human context for notifications, for example `宸ヤ綔绔?鍙穈, `MacBook Pro`, or `GPU-Server-01`.
+
+A good default model is one user-owned random topic shared across your machines, with each machine using a different display name. Example notification:
+
+```text
+宸ヤ綔绔?鍙?路 Codex task finished
+```
+
+## Manual Setup
+
+Advanced users can still use the lower-level commands directly:
+
+```bash
+agentbell init
+agentbell test
+agentbell init-hooks --target codex
+agentbell init-hooks --target claude-code
+agentbell init-hooks --target vscode-agent
+```
+
+Use manual setup when you want to provide your own topic, skip the guided Android flow, or install hooks one tool at a time.
+## Commands
+
+### `agentbell send`
+
+閻劋绨悮?hook 鐠嬪啰鏁ら敍灞藉絺闁椒绔村▎锟犫偓姘辩叀閵?
+```bash
+agentbell send --tool codex --event stop --title "Codex 鐎瑰本鍨氭禍? --message "鏉╂粎鈻奸張鍝勬珤娑撳﹦娈?Codex 瀹歌尙绮ㄩ弶鐔告拱鏉烆喕鎹㈤崝?
+```
+
+鐢摜鏁ら崣鍌涙殶閿?
+- `--tool`: `claude-code`閵嗕梗codex`閵嗕梗vscode-agent`閵嗕梗custom`
+- `--event`: `stop`閵嗕梗notification`閵嗕梗error`閵嗕梗permission`閵嗕梗custom`
+- `--title`: 闁氨鐓￠弽鍥暯閿涘苯褰查柅?- `--message`: 闁氨鐓￠崘鍛啇閿涘苯褰查柅?- `--priority`: ntfy priority閿涘苯褰查柅?- `--tags`: ntfy tags閿涘矂鈧褰块崚鍡涙閿涘苯褰查柅?- `--config`: 閹稿洤鐣鹃柊宥囩枂閺傚洣娆㈢捄顖氱窞閿涘苯褰查柅?
+婵″倹鐏夋稉宥勭炊 `title` 閹?`message`閿涘瓑gentBell 娴兼俺鍤滈崝銊ф晸閹存劙绮拋銈呭敶鐎圭櫢绱濋獮鑸电壌閹诡噣鍘ょ純顔煎瘶閸?`tool`閵嗕梗event`閵嗕梗hostname`閵嗕梗cwd`閵嗕梗timestamp`閵?
+### `agentbell test`
+
+閸欐垿鈧焦绁寸拠鏇⑩偓姘辩叀閿?
+```bash
+agentbell test
+```
+
+閺嶅洭顣介敍姝欰gentBell 濞村鐦痐
+
+閸愬懎顔愰敍姝氭俊鍌涚亯娴ｇ姷婀呴崚棰佺啊鏉╂瑦娼柅姘辩叀閿涘矁顕╅弰?AgentBell 瀹歌尙绮￠柊宥囩枂閹存劕濮涢妴淇?
+### `agentbell verify`
+
+Checks whether AgentBell is still installed correctly: config, provider settings, hook files, wrapper files, recent wrapper logs, stale paths, and optional manual notification / wrapper execution.
+
+Common uses:
+
+- A task finished but no phone notification arrived.
+- You moved the project directory.
+- You renamed or moved the project and suspect stale old-project paths.
+- You deleted or regenerated wrapper files.
+- You reinstalled Node.js.
+- You updated Codex, Claude Code, or VS Code.
+- Hooks were trusted but still do not send notifications.
+
+Examples:
+
+```bash
+agentbell verify
+agentbell verify --target codex
+agentbell verify --target vscode-agent --run-wrapper
+agentbell verify --send-test
+agentbell verify --json > agentbell-verify.json
+```
+
+Options:
+
+- `--target <target>` checks `codex`, `claude-code`, `vscode-agent`, or `all`.
+- `--send-test` sends an `AgentBell verify test` phone notification.
+- `--run-wrapper` manually runs the selected wrapper command to verify it can call AgentBell.
+- `--dry-run` only inspects files and config; it does not send notifications or run wrappers.
+- `--json` prints a structured report with masked topic values.
+Log parsing note:
+
+`verify` evaluates the latest hook run block, not every historical line in the log. Old failures are ignored once a newer successful wrapper run is recorded.
+
+中文说明：`verify` 只根据最近一次 hook/wrapper 运行判断当前状态。历史日志里的旧项目路径 / `MODULE_NOT_FOUND` 不会在最新运行成功后继续导致 `error`。
+If verify reports stale old-project paths or a missing `dist/cli.js`, refresh hooks with:
+
+```bash
+node dist\cli.js init-hooks --target all
+```
+### `agentbell doctor`
+
+鏉堟挸鍤悳顖氼暔鐠囧﹥鏌囨穱鈩冧紖閿涘矂鈧倸鎮庢径宥呭煑缂佹瑥鍩嗘禍鐑樺笓閺屻儻绱?
+```bash
+agentbell doctor
+```
+
+閸栧懎鎯堥柊宥囩枂閸欘垵顕伴幀褋鈧垢rovider閵嗕苟tfy server閵嗕辜opic 閺勵垰鎯佺€涙ê婀妴浣搁挬閸欒埇鈧弓ostname閵嗕菇sername閵嗕恭wd閵嗕腐ode 閻楀牊婀伴妴涓哃I 鐠嬪啰鏁ょ捄顖氱窞閸滃本甯归懡?hook 閸涙垝鎶ら妴?
+### `agentbell init`
+
+娴溿倓绨板蹇曟晸閹存劙鍘ょ純顕嗙窗
+
+```bash
+agentbell init
+```
+
+姒涙顓婚崘娆忓弳閿?
+```text
+~/.agentbell/config.json
+```
+
+闁板秶鐤嗙粈杞扮伐閿?
+```json
+{
+  "provider": "ntfy",
+  "ntfy": {
+    "server": "https://ntfy.sh",
+    "topic": "your-long-random-topic",
+    "priority": "high",
+    "tags": ["computer"]
+  },
+  "localNotification": {
+    "enabled": true
+  },
+  "includeContext": {
+    "hostname": true,
+    "cwd": true,
+    "timestamp": true
+  }
+}
+```
+
+閸?macOS/Linux 娑撳绱濋柊宥囩枂閺傚洣娆㈡导姘晼闁插繗顔曠純顔昏礋 `600` 閺夊啴妾洪妴淇塱ndows 娑撳﹣绱扮捄瀹犵箖 POSIX 閺夊啴妾虹拋鍓х枂閵?
+### `agentbell init-hooks`
+
+閻㈢喐鍨?hook 闁板秶鐤嗗Ο鈩冩緲閿?
+```bash
+agentbell init-hooks --target claude-code
+agentbell init-hooks --target codex
+agentbell init-hooks --target vscode-agent
+agentbell init-hooks --target all
+```
+
+AgentBell 娑撳秳绱扮划妤佹瘹鐟曞棛娲婂鍙夋箒闁板秶鐤嗛妴鍌氬嚒閺?JSON 閺傚洣娆㈡导姘帥婢跺洣鍞ゆ稉?`.bak-閺冨爼妫块幋鐮㈤敍宀€鍔ч崥搴℃晼闁插繐浠?JSON merge閵嗗倸顩ч弸婊冨嚒閺堝鏋冩禒鏈电瑝閺勵垰鎮庡▔?JSON閿涘奔绱伴悽鐔稿灇 snippet 閺傚洣娆㈤獮鑸靛絹缁€杞版眽瀹搞儱鎮庨獮韬测偓?
+Preview hook changes without writing files:
+
+```bash
+agentbell init-hooks --target codex --dry-run
+agentbell init-hooks --target all --dry-run
+```
+
+Dry-run prints the target config paths, whether existing config was detected, what a real run would merge, and the hook snippet that would be generated. It does not write files and does not create backups.
+
+## Claude Code Example
+
+閻╊喗鐖ｉ弬鍥︽閿?
+```text
+~/.claude/settings.json
+```
+
+閻╊喗鐖ｉ弫鍫熺亯閿?
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agentbell send --tool claude-code --event stop"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agentbell send --tool claude-code --event notification"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Codex Example
+
+閻╊喗鐖ｉ弬鍥︽閿?
+```text
+~/.codex/hooks.json
+```
+
+閻╊喗鐖ｉ弫鍫熺亯閿?
+```json
+{
+  "hooks": {
+    "stop": [
+      {
+        "command": "agentbell send --tool codex --event stop"
+      }
+    ]
+  }
+}
+```
+
+AgentBell 鏉╂ü绱伴悽鐔稿灇閿?
+```text
+~/.agentbell/snippets/codex-hooks.json
+```
+
+Codex hook 闁板秶鐤嗛弽鐓庣础閸欘垵鍏橀梾蹇曞閺堫剙褰夐崠鏍モ偓鍌濆娴ｇ姷娈?Codex 閻楀牊婀版担璺ㄦ暏娑撳秴鎮?schema閿涘矁顕幎?snippet 娑擃厾娈戦崨鎴掓姢鏉╀胶些閸掓媽顕氶悧鍫熸拱鐟曚焦鐪伴惃鍕秴缂冾喓鈧?
+### Codex Windows Wrapper
+
+On Windows, AgentBell writes a `.cmd` wrapper and points Codex to that wrapper instead of embedding a long `node.exe ... cli.js ...` command directly in `hooks.json`.
+
+Target files:
+
+```text
+~/.codex/hooks.json
+~/.agentbell/hooks/codex-stop.cmd
+~/.agentbell/snippets/codex-hooks.json
+```
+
+Verified Windows hook shape:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "commandWindows": "cmd /d /s /c \"C:\\Users\\<user>\\.agentbell\\hooks\\codex-stop.cmd\"",
+            "command": "cmd /d /s /c \"C:\\Users\\<user>\\.agentbell\\hooks\\codex-stop.cmd\"",
+            "timeout": 30,
+            "statusMessage": "Sending AgentBell notification"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The wrapper logs to:
+
+```text
+~/.agentbell/codex-hook-fired.log
+```
+
+If the log contains `Notification sent.` but your phone does not receive anything, troubleshoot ntfy, Android notification permissions, and battery optimization. If the log file does not exist, Codex did not execute the hook or the hook was not trusted.
+
+## VS Code Agent Example
+
+閻╊喗鐖ｉ弬鍥︽閺勵垰浼愭担婊冨隘缁狙囧帳缂冾噯绱?
+```text
+.github/hooks/agentbell.json
+```
+
+閻╊喗鐖ｉ弫鍫熺亯閿?
+```json
+{
+  "name": "agentbell",
+  "description": "Notify Android via AgentBell when VS Code Agent / Copilot Agent stops.",
+  "hooks": {
+    "stop": [
+      {
+        "command": "agentbell send --tool vscode-agent --event stop"
+      }
+    ]
+  }
+}
+```
+
+閸楀厖濞囪ぐ鎾冲閻╊喖缍嶆稉宥嗘Ц git 妞ゅ湱娲伴敍瀛塯entBell 娑旂喎鍘戠拋鍝ユ晸閹存劘绻栨稉?workspace hook 閺傚洣娆㈤敍灞借嫙娴兼碍褰佺粈杞扮稑绾喛顓荤€圭偤妾銉ュ徔閺勵垰鎯佺拠璇插絿鐎瑰啨鈧?
+## Real Hook Verification
+
+Hook schemas can change across AI coding tools. AgentBell keeps the templates small and visible so you can verify them with the tool version you actually run.
+
+### Codex
+
+Preview the Codex hook first:
+
+```bash
+agentbell init-hooks --target codex --dry-run
+```
+
+Then write the hook:
+
+```bash
+agentbell init-hooks --target codex
+```
+
+Run a minimal Codex task, for example asking it to inspect a tiny file or answer a short codebase question. When the task stops, you should receive an ntfy notification from `agentbell send --tool codex --event stop`.
+
+If no notification arrives, run:
+
+```bash
+agentbell doctor
+agentbell doctor --json
+agentbell test
+```
+
+Check that the config path exists, the ntfy server is reachable, and the command shown in the dry-run output is valid in the same shell/environment where Codex runs.
+
+### Claude Code
+
+Preview or write Claude Code hooks:
+
+```bash
+agentbell init-hooks --target claude-code --dry-run
+agentbell init-hooks --target claude-code
+```
+
+To verify the Stop hook, run a small Claude Code task and let it finish normally. You should receive a notification for `--tool claude-code --event stop`.
+
+To verify the Notification hook, trigger a Claude Code state that asks for user attention, such as waiting for input or a permission-related notification. You should receive a notification for `--tool claude-code --event notification`.
+
+Use the event name to distinguish states:
+
+- `stop`: the agent finished the current task or turn.
+- `notification`: the agent is asking for attention, often because it is waiting for input or needs user action.
+
+If the Stop hook works but Notification does not, inspect the installed Claude Code version and its hook documentation. The event name or schema may have changed.
+
+## Claude Code Verification
+
+AgentBell prepares Claude Code hooks with this shape:
+
+```text
+hooks.Stop[].hooks[]
+hooks.Notification[].hooks[]
+```
+
+Each handler uses `type: "command"` and calls `agentbell send`. On Windows, Claude Code runs hook commands through Git Bash / shell, so AgentBell writes project-local `.sh` wrappers instead of `.cmd` wrappers:
+
+```text
+<projectRoot>\.agentbell-hooks\claude-stop.sh
+<projectRoot>\.agentbell-hooks\claude-notification.sh
+```
+
+Both wrappers log to:
+
+```text
+<projectRoot>\.agentbell-hooks\claude-hook-fired.log
+```
+
+The generated Claude Code commands look like:
+
+```bash
+bash G:/learning/AgentBell/.agentbell-hooks/claude-stop.sh
+bash G:/learning/AgentBell/.agentbell-hooks/claude-notification.sh
+```
+
+Wrapper timestamps use an ASCII-safe UTC format, `date -u +"%Y-%m-%dT%H:%M:%SZ"`, to avoid mojibake on Windows systems with non-English locale output.
+
+Preview the files:
+
+```bash
+agentbell init-hooks --target claude-code --dry-run
+```
+
+Write the hooks:
+
+```bash
+agentbell init-hooks --target claude-code
+```
+
+After changing Claude Code hooks, trust or allow the hook if Claude Code prompts you. To verify `Stop`, run a tiny Claude Code task and let it finish. To verify `Notification`, trigger a state where Claude Code waits for user attention, such as input or permission. If no phone notification arrives, check `<projectRoot>\.agentbell-hooks\claude-hook-fired.log` first. If the log file does not exist, Claude Code did not execute or trust the hook. If the log contains `Notification sent.`, troubleshoot ntfy and Android notification delivery.
+
+### VS Code Agent / Copilot Agent
+
+VS Code Agent / Copilot Agent support is treated as a workspace hook. AgentBell writes:
+
+```text
+.github/hooks/agentbell.json
+```
+
+Preview or write it from the workspace root:
+
+```bash
+agentbell init-hooks --target vscode-agent --dry-run
+agentbell init-hooks --target vscode-agent
+```
+
+This capability may vary by VS Code and Copilot Agent version. After writing the file, reload VS Code, run a small workspace agent task, and confirm whether the hook command is executed. If it is not triggered, manually compare `.github/hooks/agentbell.json` with the hook format expected by your VS Code version, then move the command into the supported location.
+
+Use `agentbell doctor` inside the same workspace terminal to confirm the CLI path, Node version, current working directory, and config file location.
+
+## Verified: Codex VS Code Extension on Windows
+
+The VS Code Codex extension has been manually verified on Windows with AgentBell:
+
+- `UserPromptSubmit` and `Stop` hooks can be triggered by the extension.
+- `Stop` hook successfully calls AgentBell through the generated `.cmd` wrapper.
+- The full path works: Codex Stop hook -> `.cmd` wrapper -> AgentBell -> ntfy -> Android phone notification.
+- The successful wrapper log is written to `~/.agentbell/codex-hook-fired.log`.
+
+After changing hooks, Codex may require you to trust the updated hook again. If you use WSL, configure AgentBell separately inside WSL because Windows, WSL, Remote SSH, and Dev Containers have different home directories, Node paths, and hook execution environments.
+
+## Local Desktop Notifications
+
+闂勩倓绨?ntfy 閹靛婧€閹恒劑鈧緤绱滱gentBell 閸欘垯浜掔悰銉ュ帠閺堫剙婀村宀勬桨闁氨鐓￠敍?
+- macOS: `osascript display notification`
+- Linux: 娴兼ê鍘?`notify-send`閿涘奔绗夌€涙ê婀崚娆掔儲鏉?- Windows: MVP 闂冭埖顔岀捄瀹犵箖閸欘垶娼幀褌绗夌搾宕囨畱閺堫剙婀?toast閿涘苯鑻熺紒娆忓毉閹绘劗銇?
+閺堫剙婀撮柅姘辩叀婢惰精瑙︽稉宥勭窗瑜板崬鎼?ntfy 閹靛婧€閹恒劑鈧降鈧?
+## Remote SSH / WSL / Dev Container
+
+Hook 鎼存棁顕氶崷銊ョ杽闂勫懓绻嶇悰?AI coding agent 閻ㄥ嫭婧€閸ｃ劋绗傞幍褑顢戦妴鍌涚槷婵″偊绱?
+- Remote SSH: hook 閸︺劏绻欑粙?Linux 娑撶粯婧€閹笛嗩攽閵?- WSL: hook 閸?WSL 閻滎垰顣ㄩ幍褑顢戦妴?- Dev Container: hook 閸?container 閸愬懏澧界悰灞烩偓?- 鏉╂粍甯堕悽浣冨壋: hook 閸︺劏顫︽潻婊勫付閻絻鍓抽幍褑顢戦妴?
+閸ョ姵顒濇担鐘绘付鐟曚礁婀柇锝勯嚋閻滎垰顣ㄩ柌灞界暔鐟?Node.js 20+閵嗕礁鐣ㄧ憗?AgentBell閵嗕浇绻嶇悰?`agentbell init`閿涘苯鑻熺涵顔荤箽鐠囥儳骞嗘晶鍐厴鐠佸潡妫?ntfy server閵?
+## Troubleshooting
+
+### 閹靛婧€閺€鏈电瑝閸掍即鈧氨鐓?
+閸忓牐绻嶇悰宀嬬窗
+
+```bash
+agentbell doctor
+agentbell test
+```
+
+濡偓閺屻儲澧滈張鐑樻Ц閸氾箒顓归梼鍛啊閸氬奔绔存稉?topic閵嗕苟tfy 閺勵垰鎯侀張澶愨偓姘辩叀閺夊啴妾洪妴浣规Ц閸氾箑鍙ч梻顓濈啊閻㈠灚鐫滄导妯哄閵嗕辜opic 閺勵垰鎯佺搾鍐差檮闂呭繑婧€娑撴梹鐥呴張澶庣翻闁挎瑣鈧?
+### 鏉╂粎鈻奸張鍝勬珤閺冪姵纭剁拋鍧楁６ ntfy.sh
+
+鏉╂劘顢?`agentbell doctor` 閺屻儳婀?`ntfy server access`閵嗗倸顩ч弸婊冨彆閸欏摜缍夌紒婊勫灗閺堝秴濮熼崳銊х秹缂佹粓妾洪崚鎯邦問闂?`ntfy.sh`閿涘苯褰叉禒銉ㄥ殰瀵?ntfy server閿涘瞼鍔ч崥搴℃躬 `~/.agentbell/config.json` 娑擃厺鎱ㄩ弨?`ntfy.server`閵?
+### hook 濞屄ば曢崣?
+绾喛顓?hook 闁板秶鐤嗛弬鍥︽閸︺劌顕惔鏂夸紣閸忓嘲鐤勯梽鍛邦嚢閸欐牜娈戞担宥囩枂閵嗗倷鎱ㄩ弨?hook 閸氬函绱濋柌宥呮儙閹?reload 鐎电懓绨?AI coding 瀹搞儱鍙块妴鍌氬帥閻劋绔存稉顏勭发鐏忓繒娈?agent 娴犺濮熸宀冪槈 stop hook閵?
+婵″倹鐏?Windows 娑?Codex hook 濞屸剝婀佺憴锕€褰傞柅姘辩叀閿涘矁顕Λ鈧弻?`~/.agentbell/codex-hook-fired.log`閵?
+### Windows 鐠侯垰绶為梻顕€顣?
+婵″倹鐏夐崗銊ョ湰 `agentbell` 閸涙垝鎶ら崷?hook 閻滎垰顣ㄩ柌灞肩瑝閸欘垵顫嗛敍灞藉讲娴犮儰濞囬悽?`agentbell doctor` 鏉堟挸鍤惃?`cli invocation for hooks`閵嗗倸婀張顒€婀村鈧崣鎴炴閿涘苯鐣犻崣顖濆厴閺?`node path/to/dist/cli.js`閵?
+### WSL / Remote SSH 娑?hook 鐎圭偤妾潻鎰攽娴ｅ秶鐤嗛梻顕€顣?
+鐠囧嘲婀?agent 鐎圭偤妾潻鎰攽閻滎垰顣ㄩ柌灞惧⒔鐞?`agentbell doctor`閵嗕繅indows 娑撶粯婧€閵嗕箘SL閵嗕浇绻欑粙瀣╁瘜閺堟亽鈧笍ev Container 閺勵垯绗夐崥宀€骞嗘晶鍐跨礉閸氬嫯鍤滈張澶夌瑝閸氬瞼娈?home閵嗕赋ATH閵嗕腐ode 閸滃矂鍘ょ純顔芥瀮娴犺翰鈧?
+### Cannot find module old project dist cli.js
+
+If a wrapper log contains an error like:
+
+```text
+Cannot find module '...\old-project\dist\cli.js'
+MODULE_NOT_FOUND
+```
+
+then the hook and wrapper did execute, but the active wrapper still points to an old project path. This can happen after renaming or moving the project directory.
+
+Fix:
+
+```bash
+node dist\cli.js init-hooks --target all
+agentbell verify --dry-run
+```
+### setup test failed
+
+If `agentbell setup` sends a test notification but the phone does not receive it:
+
+- Check that the topic in ntfy Android exactly matches the AgentBell topic.
+- Check the ntfy server URL.
+- Open the ntfy app once to refresh the subscription.
+- Allow notification permission.
+- Allow background running / disable battery optimization.
+- Run `agentbell doctor` and inspect warnings.
+
+If you skipped hook installation during setup, rerun `agentbell setup` or use `agentbell init-hooks --target all` after phone delivery works.
+
+It is safe to rerun setup. Existing hook files are backed up by the hook installer before merge/write where supported.
+### Cannot convert argument to a ByteString
+
+This can happen when a Node.js `fetch` header contains Chinese text, emoji, or other non-ASCII characters. ntfy supports UTF-8 header values through RFC 2047 encoded-word syntax, so AgentBell automatically encodes ntfy headers such as `Title` and `Tags`.
+
+The notification body is not header data and remains a normal UTF-8 message.
+
+If you still see this error, upgrade AgentBell and rebuild it. As a temporary workaround, use an English-only `--title` and ASCII-only `--tags`.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run dev -- test
+```
+
+濞村鐦导?mock `fetch`閿涘奔绗夋导姘辨埂閻ㄥ嫬鎮?`ntfy.sh` 閸欐垼顕Ч鍌樷偓鍌氬涧閺堝鏁ら幋閿嬫▔瀵繗绻嶇悰?`agentbell test` 閹?`agentbell send` 閺冭埖澧犳导姘絺闁胶婀＄€圭偤鈧氨鐓￠妴?
+## Compatibility / Verified Matrix
+
+| Tool | Surface | OS | Hook event | Wrapper strategy | Status | Log path |
+|---|---|---|---|---|---|---|
+| Codex | VS Code extension | Windows | Stop | user `.cmd` wrapper | Verified | `~/.agentbell/codex-hook-fired.log` |
+| Claude Code | CLI / VS Code terminal mode | Windows | Stop | project `.sh` wrapper | Verified | `<projectRoot>/.agentbell-hooks/claude-hook-fired.log` |
+| Claude Code | CLI / VS Code terminal mode | Windows | Notification | project `.sh` wrapper | Prepared / Partially verified | `<projectRoot>/.agentbell-hooks/claude-hook-fired.log` |
+| VS Code Copilot Agent | VS Code Agent mode | Windows | Stop | project `.cmd` wrapper | Verified | `<projectRoot>/.agentbell-hooks/copilot-hook-fired.log` |
+| Remote SSH / WSL / Dev Container | Various | Various | TBD | TBD | Not verified | TBD |
+
+Verified means the full chain reached Android notification on the author's Windows machine. Claude Code Notification is prepared but should not be treated as fully verified until a real Notification event is tested. VS Code Agent hooks are still a Preview capability, so re-verify after VS Code or Copilot updates.
+
+## Verified: Codex VS Code Extension on Windows
+
+Verified path:
+
+```text
+Codex Stop hook -> ~/.agentbell/hooks/codex-stop.cmd -> AgentBell -> ntfy -> Android
+```
+
+Install or refresh the hook:
+
+```bash
+node dist\cli.js init-hooks --target codex
+```
+
+Then restart or reload VS Code / Codex, trust the hook if prompted, run a small Codex task, and inspect:
+
+```text
+~/.agentbell/codex-hook-fired.log
+```
+
+Log interpretation:
+
+- `Notification sent.` plus exit code `0`: AgentBell successfully sent the ntfy request.
+- No log file: Codex did not execute the hook or the hook was not trusted.
+- Log exists but phone did not receive notification: troubleshoot ntfy, Android background permissions, and notification permissions.
+
+Why `.cmd` wrapper on Windows:
+
+- Directly embedding a complex `"node.exe" "cli.js" send ...` command in `~/.codex/hooks.json` is fragile on Windows because quoting, spaces, and path escaping can vary by host.
+- The generated `.cmd` wrapper gives Codex a short stable command and gives AgentBell a log file for troubleshooting.
+- Codex uses the `hooks.Stop[].hooks[]` schema and the Windows-specific `commandWindows` field.
+- After changing hooks, Codex may ask you to trust the updated hook again.
+
+## Verified: Claude Code on Windows
+
+Claude Code CLI must be available:
+
+```bash
+claude --version
+```
+
+Hooks should be visible with:
+
+```bash
+claude /hooks
+```
+
+If `/hooks` cannot find `claude`, the Claude Code CLI is not installed or `PATH` is not configured in the terminal environment.
+
+Claude Code on Windows executes hook commands through Git Bash / shell. AgentBell therefore generates project-local `.sh` wrappers, not user-home `.cmd` wrappers.
+
+Verified path:
+
+```text
+Claude Code Stop hook -> <projectRoot>/.agentbell-hooks/claude-stop.sh -> AgentBell -> ntfy -> Android
+```
+
+How to verify:
+
+```bash
+node dist\cli.js init-hooks --target claude-code
+claude /hooks
+```
+
+Confirm `Stop` and `Notification` are present, trust or allow hooks if prompted, then run a tiny Claude Code prompt:
+
+```text
+璇峰洖澶嶄竴鍙?hello锛屼笉瑕佷慨鏀规枃浠躲€?```
+
+Inspect:
+
+```text
+<projectRoot>/.agentbell-hooks/claude-hook-fired.log
+```
+
+Old logs may contain mojibake from locale-specific Windows date output. The current wrapper uses ISO-style UTC timestamps such as `2026-05-23T13:28:27Z`; after clearing old logs, new entries should be ASCII-safe.
+
+The Claude Code Notification hook is prepared / partially verified. Do not treat it as fully verified until you have triggered and confirmed a real Notification event on your machine.
+
+
+### Claude verify run-wrapper on Windows
+
+`agentbell verify --target claude-code --run-wrapper` runs the Claude `.sh` wrapper with a resolved Git Bash executable. On Windows it uses this order:
+
+1. `AGENTBELL_BASH_PATH`, if set and the file exists.
+2. `bash` found on `PATH`.
+3. Common Git for Windows paths such as `C:\Program Files\Git\bin\bash.exe`.
+
+Example:
+
+```bat
+set AGENTBELL_BASH_PATH=D:\software\git\bin\bash.exe
+agentbell verify --target claude-code --run-wrapper
+```
+
+The verify report prints the resolved bash path:
+
+```text
+[Claude Code]
+  bash: D:\software\git\bin\bash.exe
+```
+
+If manual bash execution succeeds but verify fails, run:
+
+```bash
+agentbell verify --target claude-code --run-wrapper --json
+```
+
+Compare `bashPath`, `runWrapper`, and the latest log block status. A successful latest Claude block should include `Notification sent.` and `AgentBell exit code 0`.
+
+## Verified: VS Code Copilot Agent on Windows
+
+VS Code Agent hooks are still Preview, but the Windows Stop path below has been verified with Copilot Agent mode.
+
+Verified path:
+
+```text
+VS Code Copilot Agent Stop hook -> <projectRoot>/.agentbell-hooks/copilot-stop.cmd -> AgentBell -> ntfy -> Android
+```
+
+Generated files:
+
+- Hook file: `.github/hooks/agentbell.json`
+- Wrapper: `<projectRoot>/.agentbell-hooks/copilot-stop.cmd`
+- Log: `<projectRoot>/.agentbell-hooks/copilot-hook-fired.log`
+
+How to verify:
+
+```bash
+node dist\cli.js init-hooks --target vscode-agent
+```
+
+Reload VS Code, use Copilot Chat in Agent mode to run a small task, then inspect the log file above and confirm the phone notification. The generated Windows hook command uses:
+
+```text
+cmd /d /s /c "<projectRoot>\.agentbell-hooks\copilot-stop.cmd"
+```
+
+Do not use single quotes around the wrapper path. If Windows says the wrapper path is not recognized as an internal/external command, executable program, or batch file, the hook probably used single quotes or did not pass the wrapper path through `cmd /d /s /c` with double quotes.
+
+For hook-level debugging, open `View -> Output -> GitHub Copilot Chat Hooks`.
+
+## Android ntfy Reliability Notes
+
+If notifications arrive only after opening the ntfy app, the usual cause is Android background restriction rather than AgentBell.
+
+Recommended Android settings:
+
+- Allow notifications.
+- Allow lock-screen notifications.
+- Allow background running.
+- Disable battery optimization for ntfy.
+- Allow auto-start.
+- Allow background network access.
+- In the watch/band companion app, allow forwarding ntfy notifications.
+
+The F-Droid build of ntfy may rely more heavily on a background connection. If the phone has Google services, the Play Store build may be more reliable for push delivery.
+
+Treat the ntfy topic as a secret. Do not use an easy-to-guess topic and never commit it to a public repository. Use a long random topic such as `your-long-random-topic`; when showing diagnostics publicly, mask it like `agen...q4z1`.
+
+## Known Windows Notes
+
+- Windows local desktop notification is intentionally skipped in this MVP. ntfy phone push is unaffected.
+- Codex has been verified with a user-home `.cmd` wrapper.
+- Claude Code has been verified with a project-local `.sh` wrapper.
+- VS Code Copilot Agent has been verified with a project-local `.cmd` wrapper.
+- Windows non-ASCII usernames, Git Bash path conversion, `cmd` quoting, and hook host behavior can all affect execution, so do not casually change wrapper strategy between tools.
+- Git dubious ownership does not affect AgentBell notifications, but it can block `git status`, `git diff`, or commits. Users should decide whether to configure `safe.directory`.
+- WSL, Remote SSH, Dev Containers, and Windows host shells have different home directories, Node paths, environment variables, and network behavior. Configure and verify AgentBell in the environment where the agent hook actually runs.
+
+## Next: Verify and Rich Context
+
+Now that `agentbell setup` exists, the next product step is a dedicated `agentbell verify` command for repeatable end-to-end checks after setup.
+
+Planned improvements:
+
+1. Verify config readability.
+2. Verify ntfy delivery.
+3. Verify installed hook files and wrapper paths.
+4. Print tool-specific next steps for Codex, Claude Code, and VS Code Copilot Agent.
+5. Expand notification templates with project and task context.
+
+Example topic values in docs should stay generic, such as `your-long-random-topic` or `agen...q4z1`.
+
+## Future: Rich Notification Context
+
+Future AgentBell notifications can include richer context so the phone notification tells you which machine and task finished.
+
+Possible fields:
+
+- machine display name
+- hostname
+- tool
+- event
+- project name
+- cwd
+- git branch
+- task name
+- timestamp
+
+Example:
+
+```text
+宸ヤ綔绔?鍙?路 Codex 瀹¤浠诲姟缁撴潫
+椤圭洰锛欰gentBell
+璺緞锛欸:\learning\AgentBell
+鍒嗘敮锛歮ain
+```
+
+
+
+
+
+## Rich Notification Context
+
+AgentBell now builds richer default notification content when `--title` or `--message` is not provided. The default context can include:
+
+- machine display name
+- hostname
+- tool display name
+- raw tool id
+- event and event label
+- task name
+- project name
+- cwd
+- git branch
+- local timestamp
+- ISO timestamp
+
+Example notification:
+
+```text
+宸ヤ綔绔?鍙?路 Codex 瀹¤浠诲姟缁撴潫
+
+椤圭洰锛欰gentBell
+璺緞锛欸:\learning\AgentBell
+鍒嗘敮锛歮ain
+浜嬩欢锛歴top
+鏃堕棿锛?026-05-23 22:45
+```
+
+Useful `send` options:
+
+```bash
+agentbell send --tool codex --event stop --task "瀹¤浠诲姟"
+agentbell send --tool claude-code --event stop --project AgentBell --task "README 鏇存柊"
+agentbell send --tool vscode-agent --event stop --cwd G:\learning\AgentBell --branch main
+```
+
+Explicit `--title` and `--message` still win. Use them when a hook wrapper needs an exact fixed message.
+
+## Machine Display Name
+
+The ntfy topic is a secret transport address, not a human-readable machine name. Do not use your topic as a display name and do not commit it to a public repository.
+
+Use `profile.name` in `~/.agentbell/config.json` for friendly notification context:
+
+```json
+{
+  "profile": {
+    "name": "宸ヤ綔绔?鍙?
+  }
+}
+```
+
+A practical setup is one long random topic per user, shared across your own machines, with a different `profile.name` on each machine.
+
+
+### Hooks use rich context by default
+
+Generated Stop wrappers now let `agentbell send` build the notification from rich context. They do not hard-code simple `--title` / `--message` values by default.
+
+To customize hook notifications, create `.agentbell.json` in the project:
+
+```json
+{
+  "projectName": "AgentBell",
+  "defaultTaskName": "瀹¤浠诲姟"
+}
+```
+
+Then regenerate hooks:
+
+```bash
+agentbell init-hooks --target all
+```
+
+Project-local wrappers such as Claude Code and VS Code Copilot Agent pass `--cwd <projectRoot>` so AgentBell can read `.agentbell.json`, `package.json`, and git branch context. Codex uses a user-level wrapper and normally relies on the hook runtime cwd.
+
+Example hook notification:
+
+```text
+宸ヤ綔绔?鍙?路 Codex 瀹¤浠诲姟缁撴潫
+椤圭洰锛欰gentBell
+璺緞锛欸:\learning\AgentBell
+鍒嗘敮锛歮ain
+浜嬩欢锛歴top
+鏃堕棿锛?026-05-23 22:45
+```
+## Project Config
+
+AgentBell can also read optional project-level config from `.agentbell.json` in the current working directory.
+
+```json
+{
+  "projectName": "AgentBell",
+  "defaultTaskName": "瀹¤浠诲姟"
+}
+```
+
+Create it with:
+
+```bash
+agentbell project init --name AgentBell --task "瀹¤浠诲姟"
+```
+
+If `.agentbell.json` already exists, `agentbell project init` will not overwrite it unless you pass `--force`. With `--force`, AgentBell writes a `.bak-<timestamp>` backup first.
+
+Project name priority:
+
+1. `agentbell send --project <name>`
+2. `.agentbell.json` `projectName`
+3. `package.json` `name`
+4. current directory name
+
+Task name priority:
+
+1. `agentbell send --task <name>`
+2. `.agentbell.json` `defaultTaskName`
+3. `浠诲姟`
+
+Project-level notification templates can override global templates:
+
+```json
+{
+  "projectName": "AgentBell",
+  "defaultTaskName": "瀹¤浠诲姟",
+  "notification": {
+    "titleTemplate": "{{machine}} 路 {{tool}} {{task}}{{eventLabelSuffix}}",
+    "messageTemplate": "椤圭洰锛歿{project}}\n璺緞锛歿{cwd}}\n鍒嗘敮锛歿{branch}}\n浜嬩欢锛歿{event}}\n鏃堕棿锛歿{timestamp}}"
+  }
+}
+```
+
+Supported template variables include `machine`, `hostname`, `tool`, `toolRaw`, `event`, `eventLabel`, `task`, `project`, `cwd`, `branch`, `timestamp`, `isoTimestamp`, and `duration`.
+
+## Setup Project Context
+
+`agentbell setup` remains safe by default and does not create `.agentbell.json` in `--yes` mode unless requested.
+
+To create project context during setup:
+
+```bash
+agentbell setup --init-project --project-name AgentBell
+```
+
+In interactive setup, AgentBell can ask whether to create `.agentbell.json` for the current project. Choosing no leaves the project untouched.
+
+
+