M-Huzaifa-Awan/explain-tool

# explain-tool 一个 Claude Code hook，可在权限提示处直接显示即将执行的工具调用的简要英文说明及其所需的访问权限。 你不再只能看到单调的 `Bash: rm -rf node_modules`，而是在按下允许之前，就能清楚了解它的具体含义和风险程度。 作者：Muhammad Huzaifa Awan ## 它会显示什么 ``` [ Permission check · Bash ] $ rm -rf node_modules Does: Permanently deletes node_modules and everything inside it. This cannot be undone. Wants: shell / terminal access Risk: HIGH (recursive force delete) ``` 它涵盖了 Bash 和 PowerShell（包含对 `rm -rf` / `Remove-Item -Recurse -Force`、`sudo`、强制 push、将远程脚本通过管道传递给 shell 以及机密文件等操作的风险检测）、Write、Edit、Read、Glob、Grep、WebFetch、WebSearch、子 agent 以及任何 MCP 集成。路径会同时匹配 `/` 和 `\`，因此机密文件检测在 Windows 上的工作方式与在 macOS 和 Linux 上完全一致。 ## 工作原理 该 hook 在 `PermissionRequest` 事件上运行，该事件仅在 Claude Code 准备要求你允许或拒绝某项操作时触发。它会读取工具名称和输入内容，对操作进行分类，并返回一条单独的 `systemMessage`。它从不返回权限决策，因此你常规的允许/拒绝提示不会受到影响。如果出现任何问题，它会保持静默并干净地退出，绝不会阻碍你的工作。 ## 安装（仅需一条命令） 下载或克隆此 repo，然后运行安装程序： ``` git clone https://github.com/M-Huzaifa-Awan/explain-tool.git cd explain-tool python install.py ``` 在 macOS / Linux 上，如果找不到 `python`，请使用 `python3 install.py`。 就是这样。安装程序会将 hook 复制到 `~/.claude/hooks/` 并在 `~/.claude/settings.json` 中为你注册——无需编辑 JSON。它会将所有现有设置备份到 `settings.json.bak`，绝不会触碰你的其他 hook，而且再次运行它只会进行原地更新（不会产生重复项）。 然后**开启一个新的 Claude Code 会话**（hook 在启动时加载）并运行 `/hooks` 以确认其已注册。 以后若要移除它： ``` python install.py --uninstall ```

手动安装（如果你更倾向于自己动手）

1. 复制脚本并使其可执行： mkdir -p ~/.claude/hooks cp explain_tool.py ~/.claude/hooks/explain_tool.py chmod +x ~/.claude/hooks/explain_tool.py 2. 在 `~/.claude/settings.json` 中注册 hook（如果你已有该文件，请将其合并到现有文件中）： { "hooks": { "PermissionRequest": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "python3 \"$HOME/.claude/hooks/explain_tool.py\"" } ] } ] } } 在 Windows 上，请使用 `python` 代替 `python3`，并将路径指向 `%USERPROFILE%\.claude\hooks\explain_tool.py`。 3. 开启一个新的 Claude Code 会话并运行 `/hooks` 进行确认。

## 在没有 Claude Code 的情况下进行测试 ``` echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf build"}}' \ | python3 ~/.claude/hooks/explain_tool.py ``` 你应该会得到一个包含 `systemMessage` 的 JSON 对象。 ## 注意事项 - 需要 Python 3（仅使用标准库，无其他依赖）。适用于 Windows、macOS 和 Linux。 - 如果要解释每一次工具调用（包括那些已在你的允许列表中的调用），请将事件从 `PermissionRequest` 更改为 `PreToolUse`。同一个脚本对两者都适用。`PermissionRequest` 是推荐的默认设置，因为它只在你实际被询问时才会发声。 - 风险标签仅供参考，并非绝对保证。请务必阅读命令本身。

标签：AI扩展, Claude Code, 代码审查, 开发辅助工具, 权限管理, 模型越狱, 逆向工具