agent-doorbell

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Doorbell

Use this skill to manage runtime hooks that ring the user's attention back when an Agent stops or needs input. The hook, not the Agent's final-response discipline, owns reliable reminders.

使用此技能管理运行时钩子，当Agent停止运行或需要输入时提醒用户注意。可靠的提醒由钩子负责，而非Agent的最终响应规则。

Core Rule

核心规则

This skill is a hook manager. When the latest user request explicitly invokes

agent-doorbell

, install or update the default runtime hook unless the request says to uninstall, remove, or disable it. Do not use this skill merely because the Agent is about to send a final response.

Once a hook is installed, the runtime calls an OS-native runner and returns quickly. Do not also run a manual doorbell helper for the same stop event.

此技能是钩子管理器。当用户最新请求明确调用

agent-doorbell

时，安装或更新默认运行时钩子，除非请求要求卸载、移除或禁用它。请勿仅因Agent即将发送最终响应就使用此技能。

钩子安装完成后，运行时会调用操作系统原生的执行程序并快速返回。请勿针对同一停止事件同时运行手动门铃助手。

Action Routing

动作路由

User intent	Action
`agent-doorbell` , install, setup, enable, update, make reminders automatic	Install or update hooks
uninstall, remove, disable, turn off doorbell hooks	Uninstall hooks
test, dry-run, preview	Run installer with `--dry-run`
ordinary final response, progress pause, or internal checklist step	Do not trigger this skill

If the user forbids tool use, shell commands, notifications, or settings changes for the turn, do not write hook settings. Explain the skipped setup briefly.

用户意图	动作
`agent-doorbell` 、安装、设置、启用、更新、设置自动提醒	安装或更新钩子
卸载、移除、禁用、关闭门铃钩子	卸载钩子
测试、试运行、预览	使用 `--dry-run` 参数运行安装程序
普通最终响应、进度暂停或内部检查步骤	不触发此技能

如果用户当前禁止使用工具、Shell命令、通知或修改设置，则不要写入钩子设置。简要说明跳过的设置操作。

Runtime Defaults

运行时默认值

Runtime	Default events	Settings target	Notes
Claude Code	`Elicitation` , `PermissionRequest` , `Stop` , `StopFailure`	`~/.claude/settings.json`	Uses command hooks with `command` , `args` , `async: true` , `timeout` , and `statusMessage` .
Gemini CLI	`AfterAgent` , `Notification`	`~/.gemini/settings.json`	Uses command hooks with a command string and millisecond timeout. The runner emits Gemini-compatible JSON output.
Codex	`Stop`	`~/.codex/hooks.json`	Uses a command string and second-based timeout. `PermissionRequest` is opt-in because it fires for tool approval requests and can be noisy.
Other Agent runtimes	Runtime-specific stop/finalize/input events	Runtime-specific local settings	Configure only when the runtime has documented lifecycle hooks. Connect those hooks to the OS-native runner.

Operating system	Default hook runner	Notes
Windows	`powershell.exe` + `scripts/hook-runner.ps1`	Uses `ring.ps1` for native beep and tray/desktop notification.
macOS	`/bin/sh` + `scripts/hook-runner.sh`	Uses `osascript` notification and beep.
Linux	`/bin/sh` + `scripts/hook-runner.sh`	Uses `notify-send` when available, then terminal bell fallback.

Prefer user-local settings by default because hook commands contain machine-local executable and skill paths. Use project-local settings only when the user asks for per-project behavior.

Do not chase every Agent runtime. Support only runtimes with documented lifecycle hooks. When no documented hook exists, say that reliable automatic stop reminders are not available through this skill yet.

运行时	默认事件	设置目标	说明
Claude Code	`Elicitation` 、 `PermissionRequest` 、 `Stop` 、 `StopFailure`	`~/.claude/settings.json`	使用带有 `command` 、 `args` 、 `async: true` 、 `timeout` 和 `statusMessage` 的命令钩子。
Gemini CLI	`AfterAgent` 、 `Notification`	`~/.gemini/settings.json`	使用带有命令字符串和毫秒级超时的命令钩子。执行程序会输出兼容Gemini的JSON格式内容。
Codex	`Stop`	`~/.codex/hooks.json`	使用命令字符串和秒级超时。 `PermissionRequest` 为可选开启项，因为它会在工具审批请求时触发，可能产生较多提醒。
其他Agent运行时	运行时特定的停止/结束/输入事件	运行时特定的本地设置	仅当运行时有文档化的生命周期钩子时才进行配置。将这些钩子连接到操作系统原生的执行程序。

操作系统	默认钩子执行程序	说明
Windows	`powershell.exe` + `scripts/hook-runner.ps1`	使用 `ring.ps1` 实现原生蜂鸣和托盘/桌面通知。
macOS	`/bin/sh` + `scripts/hook-runner.sh`	使用 `osascript` 实现通知和蜂鸣。
Linux	`/bin/sh` + `scripts/hook-runner.sh`	优先使用 `notify-send` ，若不可用则回退到终端提示音。

默认优先使用用户本地设置，因为钩子命令包含机器本地的可执行文件和技能路径。仅当用户要求按项目配置时，才使用项目本地设置。

无需支持所有Agent运行时。仅支持有文档化生命周期钩子的运行时。当不存在文档化钩子时，说明此技能暂不支持可靠的自动停止提醒。

Install Workflow

安装流程

Resolve the skill directory that contains this
```
SKILL.md
```
.
Choose the runtime.
- Use
```
claude
```
  when the request mentions Claude Code or the current surface is Claude Code.
- Use
```
gemini
```
  when the request mentions Gemini CLI.
- Use
```
codex
```
  when the request mentions Codex or the current surface is Codex.
- If the runtime is unclear, ask one short question instead of writing the wrong settings file.
Choose the action.
- Default action is install/update when the user explicitly invokes
```
agent-doorbell
```
  .
- Use uninstall when the user says
```
uninstall
```
  ,
```
remove
```
  ,
```
disable
```
  , or equivalent wording.
Run the bundled installer when one is available, or edit the target settings JSON directly using the hook shapes below.

Claude Code install:

powershell

.\scripts\install-hooks.ps1 -Runtime claude -Scope user

Claude Code uninstall:

powershell

.\scripts\install-hooks.ps1 -Action uninstall -Runtime claude -Scope user

Gemini CLI install:

powershell

.\scripts\install-hooks.ps1 -Runtime gemini -Scope user

Gemini CLI uninstall:

powershell

.\scripts\install-hooks.ps1 -Action uninstall -Runtime gemini -Scope user

Codex install/update:

powershell

.\scripts\install-hooks.ps1 -Runtime codex -Scope user

Codex uninstall:

powershell

.\scripts\install-hooks.ps1 -Action uninstall -Runtime codex -Scope user

Node convenience installer examples, useful on macOS/Linux when Node is available:

bash

node scripts/install-hooks.js --runtime claude --scope user
node scripts/install-hooks.js uninstall --runtime claude --scope user
node scripts/install-hooks.js --runtime gemini --scope user
node scripts/install-hooks.js --runtime codex --scope user

Project-local examples:

bash

node scripts/install-hooks.js --runtime claude --scope project-local --project-root .
node scripts/install-hooks.js --runtime gemini --scope project --project-root .
node scripts/install-hooks.js --runtime codex --scope project --project-root .

Use

--dry-run

to preview changes without writing settings:

powershell

.\scripts\install-hooks.ps1 -Runtime claude -Scope user -DryRun

The installers are convenience tools for writing JSON. The generated hooks default to OS-native runners and do not require Node or Python at stop time. The installer is idempotent: it removes previous Agent Doorbell hook entries before writing the replacement. It removes only hooks identified by

statusMessage

name

Agent Doorbell

or a command that points to

hook-runner.ps1

hook-runner.sh

, or

hook-runner.js

; it also recognizes legacy

hook-runner.py

entries so older Python-based hooks can be replaced cleanly.

Use

--runner node

only when the user explicitly wants Node-based hooks:

bash

node scripts/install-hooks.js --runtime claude --scope user --runner node

定位包含此
```
SKILL.md
```
的技能目录。
选择运行时。
- 若请求提及Claude Code或当前环境为Claude Code，则使用
```
claude
```
  。
- 若请求提及Gemini CLI，则使用
```
gemini
```
  。
- 若请求提及Codex或当前环境为Codex，则使用
```
codex
```
  。
- 若运行时不明确，先询问一个简短问题，不要写入错误的设置文件。
选择动作。
- 当用户明确调用
```
agent-doorbell
```
  时，默认动作是安装/更新。
- 当用户提及
```
uninstall
```
  、
```
remove
```
  、
```
disable
```
  或类似表述时，执行卸载动作。
若有捆绑的安装程序则运行它，否则直接编辑目标设置JSON文件，使用下方的钩子格式。

Claude Code安装：

powershell

.\scripts\install-hooks.ps1 -Runtime claude -Scope user

Claude Code卸载：

powershell

.\scripts\install-hooks.ps1 -Action uninstall -Runtime claude -Scope user

Gemini CLI安装：

powershell

.\scripts\install-hooks.ps1 -Runtime gemini -Scope user

Gemini CLI卸载：

powershell

.\scripts\install-hooks.ps1 -Action uninstall -Runtime gemini -Scope user

Codex安装/更新：

powershell

.\scripts\install-hooks.ps1 -Runtime codex -Scope user

Codex卸载：

powershell

.\scripts\install-hooks.ps1 -Action uninstall -Runtime codex -Scope user

Node便捷安装示例，适用于已安装Node的macOS/Linux系统：

bash

node scripts/install-hooks.js --runtime claude --scope user
node scripts/install-hooks.js uninstall --runtime claude --scope user
node scripts/install-hooks.js --runtime gemini --scope user
node scripts/install-hooks.js --runtime codex --scope user

项目本地设置示例：

bash

node scripts/install-hooks.js --runtime claude --scope project-local --project-root .
node scripts/install-hooks.js --runtime gemini --scope project --project-root .
node scripts/install-hooks.js --runtime codex --scope project --project-root .

使用

--dry-run

参数预览更改而不写入设置：

powershell

.\scripts\install-hooks.ps1 -Runtime claude -Scope user -DryRun

安装程序是用于编写JSON的便捷工具。生成的钩子默认使用操作系统原生执行程序，停止时不需要Node或Python。安装程序具有幂等性：在写入新钩子之前，会先移除之前的Agent Doorbell钩子条目。它只会移除

statusMessage

name

为

Agent Doorbell

，或命令指向

hook-runner.ps1

、

hook-runner.sh

或

hook-runner.js

的钩子；同时也能识别旧版

hook-runner.py

条目，以便干净地替换基于Python的旧钩子。

仅当用户明确要求基于Node的钩子时，才使用

--runner node

参数：

bash

node scripts/install-hooks.js --runtime claude --scope user --runner node

Hook Shapes

钩子格式

Claude Code on Windows writes entries equivalent to this shape:

json

{
  "hooks": {
    "Stop": [{"hooks": [{"type": "command", "command": "powershell.exe", "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "<skill-path>/scripts/hook-runner.ps1", "-Event", "Stop", "-Reason", "done", "-Mode", "both", "-Intensity", "normal", "-Output", "none"], "async": true, "timeout": 10, "statusMessage": "Agent Doorbell"}]}]
  }
}

Claude Code on macOS/Linux uses

/bin/sh

with

scripts/hook-runner.sh

and the same event/reason arguments.

Gemini CLI on macOS/Linux writes entries equivalent to this shape, with a shell-quoted command string:

json

{
  "hooks": {
    "AfterAgent": [{"hooks": [{"name": "Agent Doorbell", "type": "command", "command": "/bin/sh <skill-path>/scripts/hook-runner.sh --event AfterAgent --reason done --mode both --intensity normal --output gemini", "timeout": 10000, "description": "Ring a non-blocking Agent Doorbell cue when the agent stops or needs attention."}]}]
  }
}

Gemini CLI on Windows uses a

powershell.exe ... hook-runner.ps1 ... -Output gemini

command string instead.

Windows系统上的Claude Code会写入如下格式的条目：

json

{
  "hooks": {
    "Stop": [{"hooks": [{"type": "command", "command": "powershell.exe", "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "<skill-path>/scripts/hook-runner.ps1", "-Event", "Stop", "-Reason", "done", "-Mode", "both", "-Intensity", "normal", "-Output", "none"], "async": true, "timeout": 10, "statusMessage": "Agent Doorbell"}]}]
  }
}

macOS/Linux系统上的Claude Code使用

/bin/sh

和

scripts/hook-runner.sh

，并传入相同的事件/原因参数。

macOS/Linux系统上的Gemini CLI会写入如下格式的条目，包含Shell转义的命令字符串：

json

{
  "hooks": {
    "AfterAgent": [{"hooks": [{"name": "Agent Doorbell", "type": "command", "command": "/bin/sh <skill-path>/scripts/hook-runner.sh --event AfterAgent --reason done --mode both --intensity normal --output gemini", "timeout": 10000, "description": "Ring a non-blocking Agent Doorbell cue when the agent stops or needs attention."}]}]
  }
}

Windows系统上的Gemini CLI则使用

powershell.exe ... hook-runner.ps1 ... -Output gemini

命令字符串。

Boundaries

边界限制

Do not install hooks just because the Agent is stopping.
Do not ring manually as a fallback for ordinary final responses.
Do not write shareable project settings with machine-local paths unless the user explicitly chooses project scope.
Do not include secrets, private identifiers, raw logs, or large output in hook summaries.
Do not open windows, steal focus, or loop sounds.
Keep unsupported runtimes honest: if there is no documented lifecycle hook, say that reliable automatic stop reminders are not available through this skill yet.
Do not generate default hook configs that depend on Python or Node. Use OS-native runners by default.

请勿仅因Agent即将停止就安装钩子。
请勿针对普通最终响应手动触发提醒作为回退方案。
除非用户明确选择项目范围，否则不要写入包含机器本地路径的可共享项目设置。
请勿在钩子摘要中包含机密信息、私有标识符、原始日志或大量输出。
请勿打开窗口、抢占焦点或循环播放声音。
如实告知不支持的运行时：如果没有文档化的生命周期钩子，说明此技能暂不支持可靠的自动停止提醒。
请勿生成依赖Python或Node的默认钩子配置。默认使用操作系统原生执行程序。

Verification

验证

For test commands and expected behavior, see

references/verification.md

测试命令和预期行为请参考

references/verification.md

。