1. 项目概述：当Claude Code遇上斯蒂芬·库里

如果你和我一样，是个既写代码又看NBA的开发者，那你肯定懂那种感觉：深夜调试，对着终端里滚动的日志，世界安静得只剩下键盘声。Claude Code是个好帮手，但它干活时太“安静”了——一个工具调用，一次权限请求，会话结束，所有这些关键节点都悄无声息。你不得不频繁切回界面查看进度，工作流被打断，心流状态也难以维持。

claudecode-curry 这个项目，用一种极其巧妙且充满趣味的方式，解决了这个“静默工作”的痛点。它的核心创意是：让NBA巨星、金州勇士队的灵魂人物斯蒂芬·库里，来为你“解说”每一次Claude Code的操作。想象一下，当你提交一个提示（Prompt），通知中心弹出“🏀 Chef Curry cooking”；当Claude开始执行一个Bash命令，耳边响起“💨 Fast Break”的提示音；甚至当会话结束时，自动播放库里那记经典的“Bang Bang”绝杀视频。它把枯燥的开发监控，变成了一场充满惊喜的篮球主题秀。

这个项目本质上是一套针对Claude Code的 事件钩子（Hooks）系统 。它通过修改Claude Code的配置文件，在特定事件（如用户提交提示、工具调用前、收到通知、会话停止）触发时，执行一个外部Python脚本。这个脚本会随机选取一句库里风格的台词，播放对应的音效，发送macOS桌面通知，并在重要时刻（如权限超时、会话结束）自动在浏览器中打开相关的经典比赛视频片段。

我实际使用了几周，感受远超预期。它不仅仅是个“玩具”。在需要长时间运行复杂命令（比如构建Docker镜像或跑数据训练）时，我不再需要死盯着终端。库里的一句“📼 Scouting”（意为“侦察”，对应文件读取操作）或一声清脆的投篮音效，就能让我瞬间知道Claude正在哪个阶段工作，是陷入了文件检索还是开始了代码生成。它用一种极低的认知成本，提供了高效的异步状态反馈。下面，我就带你彻底拆解这个项目，从原理、安装、定制到深度使用，让你也能拥有这位“数字球场”上的MVP助手。

2. 核心原理与架构设计解析

要玩转 claudecode-curry ，甚至基于它的思路定制自己的通知系统，必须吃透其工作原理。它的设计非常精巧，完全遵循了“非侵入式”和“无阻塞”两大原则，这正是其稳定性的基石。

2.1 钩子（Hooks）机制：如何让Claude Code“开口说话”

Claude Code（此处指由Anthropic公司开发的IDE插件或独立应用）作为一个先进的AI编程助手，其内部有一套完整的事件总线。当用户进行操作或Claude自身触发动作时，这些事件会被广播。 claudecode-curry 项目的核心，就是利用了Claude Code提供给高级用户的 自定义脚本钩子 功能。

在macOS系统上，Claude Code的配置通常存储在用户目录下的 ~/.claude/settings.json 文件中。这个JSON文件里，有一个专门用于配置外部钩子的字段（具体名称可能因版本而异，常见如 hooks 或 eventHandlers ）。 install.py 脚本的工作，就是智能地定位并修改这个文件。

钩子的本质 ，是一系列预定义的键值对。键（Key）是事件名称，例如 UserPromptSubmit 、 PreToolUse 、 Stop ；值（Value）则是一个命令行字符串，指定当该事件发生时，需要执行的外部命令。 claudecode-curry 的安装脚本，会将自己的 curry_alerts.py 脚本路径和对应的事件参数，写入到这些钩子配置中。

例如，安装后，你的 settings.json 中可能会新增如下片段：

{
  "hooks": {
    "UserPromptSubmit": "/usr/bin/python3 /path/to/claudecode-curry/curry_alerts.py UserPromptSubmit",
    "Stop": "/usr/bin/python3 /path/to/claudecode-curry/curry_alerts.py Stop"
    // ... 其他事件钩子
  }
}

这样，每当你在Claude Code中按下回车提交提示，Claude Code内部就会触发 UserPromptSubmit 事件，并自动在后台执行上面配置的那条Python命令。

注意 ：直接手动编辑 settings.json 是有风险的，尤其是格式错误会导致Claude Code无法启动。 install.py 脚本的重要性就在于，它采用程序化的方式安全地合并配置，避免了手动修改可能带来的JSON语法错误或键值冲突。

2.2 事件驱动与进程分离：为何流畅不卡顿

你可能会担心：频繁执行外部Python脚本，会不会拖慢Claude Code的响应速度？这正是本项目设计上的第二个精妙之处： 即时分叉与脱离（Fork and Detach） 。

查看 curry_alerts.py 的核心逻辑（基于其描述推断），它绝不会让Claude Code等待自己运行完毕。典型的实现模式如下：

1. 脚本启动 ：Claude Code同步执行钩子命令，启动 curry_alerts.py 。
2. 快速处理 ：脚本立即读取必要的参数（事件类型）和上下文（通过标准输入 stdin 传入，例如工具名称、通知信息）。
3. 分叉脱离 ：脚本使用Python的 os.fork() 或 subprocess.Popen 配合 detach 标志，立即创建一个新的、独立的子进程来执行“播放声音”、“发送通知”、“打开浏览器”这些可能耗时的操作。
4. 主进程退出 ：父进程（即被Claude Code直接调用的进程）在完成分叉后立刻退出，返回一个成功状态码给Claude Code。

整个流程在毫秒级内完成。从Claude Code的视角来看，它只是启动了一个瞬间就结束的小脚本，没有任何等待。所有“重活”（网络请求、调用系统API）都由那个被分离到后台的子进程默默完成。这种设计确保了无论你的通知逻辑多复杂，都不会影响Claude Code本身的交互流畅性。

2.3 配置与资源管理：个性化定制的基石

项目的可定制性源于其清晰的配置架构。 curry.config.json 文件是整个系统的“大脑”，它采用事件名作为键，每个事件对应一个完整的配置对象。

{
  "UserPromptSubmit": {
    "enabled": true,
    "title": "🏀 Chef Curry",
    "messages": ["Chef Curry cooking!", "Let's get to work.", "Dropping dimes..."],
    "sound": "sounds/swish.mp3",
    "probability": 1.0
  }
}

• enabled : 这是全局开关。如果你觉得某个事件的通知太频繁（比如每次读文件都提示），可以单独关闭，而不是修改Claude Code的钩子，更加安全便捷。
• messages : 消息池。脚本每次会随机选取一条，避免了重复提示带来的枯燥感。支持 {tool} 和 {message} 占位符，能动态插入工具名或Claude的通知内容，让提示语更贴合上下文。
• sound : 音效文件路径。项目自带一个 sounds/ 目录存放篮球主题音效（如投篮入网的“swish”、哨声、终场蜂鸣器）。你也可以指向系统音效，如 "/System/Library/Sounds/Ping.aiff" ，实现风格的混搭。
• video_url : 这是“高光时刻”功能的核心。对于 Notification （权限超时）和 Stop （会话结束）这类标志性事件，配置中的YouTube链接会被自动在默认浏览器中打开，瞬间将你从代码世界拉回激动人心的球场时刻。
• probability : 概率因子。这是一个非常实用的设计。例如，将 PreToolUse (Read) 的概率设为0.4，意味着Claude在每次读取文件时，只有40%的几率会触发库里通知。这平衡了信息量和打扰度，对于高频但次要的事件尤其有用。

这种基于JSON的配置方式，把控制权完全交给了用户，同时保证了核心逻辑的简洁。你想让库里在什么场景下“发言”，用什么语气，配什么音效，都由这个配置文件决定。

3. 详细安装与配置指南

了解了原理，动手安装就变得非常简单。但魔鬼藏在细节里，遵循正确的步骤和了解潜在的坑点，能让你一次成功。

3.1 环境准备与前置检查

在运行任何安装命令之前，请务必确认以下几点：

1. 操作系统 ：项目严重依赖 osascript （发送通知）和 afplay （播放音频）这两个命令行工具，它们是macOS系统的原生组件。因此， 该项目仅适用于macOS 。在Linux或Windows上无法直接运行。
2. Python版本 ：确保你的系统已安装Python 3.10或更高版本。在终端输入 python3 --version 检查。建议使用Homebrew安装或管理Python版本，以获得最佳体验。
3. Claude Code ：显然，你需要已经安装并正在使用Claude Code。无论是作为独立应用还是IDE插件，确保其正在运行且版本较新（通常支持自定义钩子的功能在较新的版本中提供）。
4. Git ：用于克隆项目仓库。通常macOS已自带，可通过 git --version 检查。

3.2 两种安装模式详解

项目提供了两种安装模式，对应不同的使用场景。

全局安装模式（默认） 这是最常用的方式，会让库里通知对你所有Claude Code会话生效。

git clone https://github.com/elizabethsiegle/claudecode-curry
cd claudecode-curry
python3 install.py

执行后，脚本会：

• 自动定位你的 ~/.claude/settings.json 文件。
• 创建该文件的备份（通常为 settings.json.backup ），以防万一。
• 将定义好的事件钩子写入配置文件。
• 提示你安装完成。

项目级安装模式（ --project ） 如果你只在特定的开发项目中使用Claude Code，或者不希望全局生效，可以使用此模式。

python3 install.py --project

该模式的区别在于，它不会修改全局的 settings.json ，而是尝试在当前目录或其父目录中寻找项目特定的Claude Code配置文件（例如 .claude/settings.json ）。这需要你的Claude Code支持并已为该项目进行了独立配置。这种模式更干净，适合在多个不同风格的项目间切换。

实操心得 ：我推荐先使用全局安装模式体验完整功能。如果后续觉得在某些项目中干扰过大，再考虑使用 --uninstall 全局卸载，然后在特定的项目目录内使用 --project 模式重新安装。这样可以更精细地控制。

3.3 安装过程常见问题排查

即使步骤正确，你也可能会遇到一些问题。这里记录几个我踩过的坑：

1. 权限错误 ：如果安装脚本报错，提示无法写入 settings.json ，这通常是因为文件权限问题。尝试手动检查该文件的所有者： ls -la ~/.claude/ 。如果权限不足，可能需要使用 sudo ，但 强烈不建议 ，因为用root权限修改用户配置文件可能引发其他问题。更安全的做法是确保当前用户对该目录有写权限： chmod u+w ~/.claude/settings.json 。
2. Claude Code无法启动 ：安装后如果Claude Code打不开了，大概率是 settings.json 的JSON格式被破坏。这是备份文件派上用场的时候。关闭Claude Code，然后执行： cp ~/.claude/settings.json.backup ~/.claude/settings.json 即可恢复。然后检查 install.py 脚本的输出，看是否有错误信息。
3. 没有通知或声音 ：
   • 检查系统通知 ：首先确保macOS没有屏蔽Claude Code或终端（Terminal）的通知权限。前往“系统设置” > “通知”，找到对应应用，确保“允许通知”是打开的。
   • 检查Python路径 ： install.py 脚本中硬编码的Python解释器路径（ /usr/bin/python3 ）可能与你实际的路径不符。你可以打开 install.py ，查看它是如何构造钩子命令的，必要时将其中的Python路径改为 which python3 命令输出的结果。
   • 手动测试脚本 ：进入项目目录，尝试手动运行警报脚本： python3 curry_alerts.py UserPromptSubmit 。观察终端是否有错误输出。这能帮你定位是钩子配置问题，还是脚本本身的运行问题。

安装成功后，重启你的Claude Code（如果它正在运行），然后尝试输入一个提示或运行一个命令。你应该立刻能看到一个来自“Chef Curry”的桌面通知，并听到清脆的音效——恭喜你，你的专属解说员已上线！

4. 事件类型与场景深度解读

claudecode-curry 将Claude Code的工作流抽象成了几个核心事件，并为每个事件赋予了独特的篮球解说风格。理解每个事件触发的时机和其设计用意，能让你更好地欣赏和利用这个工具。

4.1 开发流程中的核心事件

事件名	触发时机	默认标题	设计意图与场景
UserPromptSubmit	当你写完提示词（Prompt），按下回车或点击发送时。	🏀 Chef Curry	标志着一个新任务的开始。“主厨库里”开始为你烹饪（编写）代码。这是最常触发的事件，100%概率，给你一个明确的任务启动反馈。
PreToolUse	在Claude Code 即将调用 某个工具（如写文件、运行命令） 之前 。这是一个非常重要的事件，它让你知道Claude“想做什么”。	多种，见下表	根据工具类型细分，让你提前知晓Claude的行动意图，是准备写代码、执行命令，还是查找信息。
Notification	当Claude Code需要向你发送一条系统通知时，主要分为两类：权限请求和一般信息。	⏱️ TIMEOUT (权限) 📣 Hey (一般)	权限通知（如请求网络访问）通常需要用户交互，用“TIMEOUT”和打开“Night Night”视频来强调其重要性。一般通知则轻量提示。
Stop	当Claude Code会话被明确终止时（例如你关闭了会话窗口，或点击了停止按钮）。	🙏 Night Night	标志着一次合作任务的结束。用库里经典的“晚安”庆祝手势和“Bang Bang”绝杀视频，为成功的编码会话画上一个充满成就感的句号。

4.2 PreToolUse 事件的精细化分类

PreToolUse 事件是信息量最大的，项目根据Claude Code可能调用的不同工具类型，配置了不同的提示语和触发概率，这体现了极强的场景化设计思维。

工具类型	默认标题	概率	对应场景与解读
Write/Edit	🎯 Pulling Up	100%	Claude准备创建或修改文件。库里“拔起就投”，对应代码的精准生成。高概率提醒你：核心产出阶段开始了。
Bash	💨 Fast Break	100%	Claude准备在终端执行Shell命令。篮球中的“快攻”，对应快速、自动化的命令执行。高概率提醒你注意命令行的风险操作。
Read/Glob/Grep	📼 Scouting	40%	Claude正在读取文件、列表目录或搜索内容。篮球中的“侦察录像”，对应信息搜集阶段。较低概率，因为文件读取可能很频繁，避免过度打扰。
Web	🔭 Googling	50%	Claude正在使用网络搜索工具。库里超远三分的“望远镜”庆祝动作，对应从远端获取知识。中等概率。
Other Tools	🏀 Tool Time	30%	Claude调用其他未明确分类的工具。通用提示，最低概率，作为兜底。

这种设计让你仅凭一个通知标题和音效，就能瞬间判断Claude当前处于编码工作流的哪个环节：是在搜集信息（Scouting）、在构思代码（Pulling Up）、在执行部署（Fast Break），还是在查找资料（Googling）。这是一种高效的 状态通讯协议 。

4.3 音效与视频：沉浸感的关键

通知的视觉和听觉反馈是这个项目的灵魂。

• 音效选择 ：项目自带的音效通常包括篮球入网的“swish”声、哨声、观众欢呼声、终场蜂鸣器等。这些声音具有极高的辨识度，即使你不看屏幕，也能通过声音判断事件的严重性或类型（例如，蜂鸣器声肯定对应会话结束）。
• 视频联动 ：这是项目的“高光时刻”。在两种情况下会打开浏览器播放YouTube视频：
  1. 权限超时（ Notification - permission ） ：打开库里在季后赛命中关键球后说“Night Night”并做睡觉手势的经典片段。这用一种幽默的方式提醒你：“有个权限请求等着你呢，快来看看，不然就要‘睡觉’（超时）了。”
  2. 会话结束（ Stop ） ：打开库里那记传奇的“Bang Bang”超远三分绝杀视频。用这个来庆祝一次编码任务的完成，成就感拉满。

这种多模态反馈（文本+声音+视频）极大地增强了工具的趣味性和记忆点，也让枯燥的等待或确认过程变得愉悦。

5. 高级定制与个性化实战

默认配置已经很有趣，但真正的乐趣在于将其改造成完全属于你自己的版本。你可以替换成其他球星、其他音效，甚至改成完全不同的主题（比如科幻、航海）。

5.1 定制消息与占位符

打开 curry.config.json ，找到你想修改的事件节点。 messages 数组里的每一条字符串都会被随机选用。

活用占位符 ： 消息字符串支持 {tool} 和 {message} 动态内容。

• {tool} ：在 PreToolUse 事件中，会被替换为具体的工具名，如 bash 、 write_file 。
• {message} ：在 Notification 事件中，会被替换为Claude Code发送的实际通知内容。

例如，你可以将 PreToolUse 中 Bash 类型的消息改为：

"messages": ["💨 Fast Break! Executing: {tool}", "Running `{tool}` command, coast to coast!", "Terminal drive initiated: {tool}"]

这样，通知不仅会告诉你Claude要执行Bash，还会显示具体的工具标识，信息量更大。

5.2 集成自定义音效与系统声音

1. 添加个人音效 ：将你喜欢的 .mp3 或 .aiff 音频文件放入项目根目录的 sounds/ 文件夹下。然后在配置中引用即可，如 "sound": "sounds/my_cool_sound.mp3" 。注意音效文件不宜过长，1-2秒的短促声音最佳。
2. 使用系统内置声音 ：macOS自带大量高质量音效，路径通常在 /System/Library/Sounds/ 下。你可以打开这个目录听听看，比如 Blow.aiff （风声）、 Glass.aiff （玻璃声）、 Submarine.aiff （声纳）。在配置中直接使用绝对路径： "sound": "/System/Library/Sounds/Blow.aiff" 。这让你无需准备文件就能获得丰富的音效库。

5.3 修改概率与禁用事件

这是优化体验的关键。如果你觉得 PreToolUse (Read) 的“Scouting”通知还是太频繁，可以将概率从 0.4 调到 0.1 。

"PreToolUse": {
  "Read/Glob/Grep": {
    "probability": 0.1
  }
}

如果你完全不想在Claude进行网络搜索时收到通知，可以直接禁用：

"PreToolUse": {
  "Web": {
    "enabled": false
  }
}

5.4 主题大改造：从库里到任意主题

你可以完全脱离篮球主题，创建你自己的通知系统。这需要修改两部分：

1. 配置文件 ( curry.config.json ) ：将所有标题、消息替换成你的主题。例如，改成《星球大战》主题：
   • UserPromptSubmit : “🔮 The Force is strong with this prompt.”
   • PreToolUse (Bash) : “⚔️ Execute Order 66.”
   • Stop : “🎇 The Death Star has been destroyed.” 同时，将 sounds/ 目录下的音效换成光剑挥舞、激光枪、R2-D2叫声等。
2. 脚本与资源文件 ：你甚至可以重命名 curry_alerts.py 和目录名，以符合新主题。但注意， install.py 脚本里可能硬编码了这些名字，需要相应修改。

深度定制提示 ：对于高级用户，可以修改 curry_alerts.py 脚本，实现更复杂的功能，比如根据一天中的不同时间播放不同音效，或者将事件日志记录到文件中用于分析你的Claude Code使用习惯。

6. 故障排除与实用技巧

即使一切配置正确，在实际使用中也可能遇到一些小问题。这里汇总了一份速查表，并分享一些让体验更上一层楼的技巧。

6.1 常见问题速查表

问题现象	可能原因	解决方案
没有任何通知弹出	1. Claude Code钩子未正确安装。 2. 系统通知权限未开启。 3. Python脚本执行错误。	1. 运行 python3 install.py --uninstall 后再重装一次，观察终端输出。 2. 检查系统设置 > 通知，确保终端或Claude Code有权限。 3. 在终端手动运行 python3 curry_alerts.py UserPromptSubmit 看报错。
有通知但没声音	1. 音效文件路径错误或丢失。 2. 系统音量静音或过低。 3. afplay 命令有问题。	1. 检查配置中 sound 字段的路径，确保文件存在。 2. 检查系统声音和当前音频输出设备。 3. 在终端试运行 afplay /path/to/your/sound.mp3 看能否播放。
视频没有自动打开	1. 浏览器默认应用设置问题。 2. URL格式不正确或视频失效。 3. 脚本中打开浏览器的命令失败。	1. 确认系统默认浏览器设置正确。 2. 手动复制配置中的 video_url 到浏览器，测试链接是否有效。 3. 检查脚本权限，或尝试在脚本中将打开命令从 open 换成 open -a "Google Chrome" （指定浏览器）。
通知延迟或Claude卡顿	1. 网络问题（视频URL加载）。 2. 音效文件过大。 3. 脚本逻辑有阻塞（可能性低）。	1. 暂时移除 video_url 配置测试。 2. 确保音效文件是短小的MP3/AIFF，而非长音频。 3. 确认脚本使用了后台进程分离，可查看 curry_alerts.py 中是否有 subprocess.Popen(..., start_new_session=True) 类似代码。
卸载后Claude Code仍有旧钩子	install.py --uninstall 未能完全清理。	手动打开 ~/.claude/settings.json ，在 hooks 部分，删除所有指向 curry_alerts.py 的命令行。最稳妥的方式是直接用备份文件恢复： cp ~/.claude/settings.json.backup ~/.claude/settings.json 。

6.2 提升体验的进阶技巧

1. 结合Focus Mode使用 ：在macOS的“专注模式”中，你可以设置允许“Claude Code”或“终端”的通知通过。这样，当你开启“勿扰模式”或“工作模式”时，库里的通知依然能提醒你关键事件（如会话结束或权限请求），而不会让你被其他无关通知打扰。
2. 创建多套配置 ：你可以复制整个项目文件夹，创建不同主题的版本，比如 claudecode-curry-basketball 和 claudecode-starwars 。通过修改 install.py 中读取的配置文件名，或者准备不同的 config.json 并通过符号链接切换，就能在不同心情下使用不同的通知主题。
3. 日志记录用于分析 ：稍微修改一下 curry_alerts.py ，在每次触发事件时，将事件类型、时间戳和上下文信息追加写入一个日志文件。一周后分析这个日志，你就能清晰地看到自己使用Claude Code的模式：最常用哪些工具？每天在什么时间最活跃？这能帮你优化自己的工作习惯。
4. 低功耗模式静音 ：可以在脚本中加入一个判断，如果笔记本电脑处于电池模式且电量低于20%，则自动将 sound 设置为 null ，只保留静默通知，节省电量并避免在安静场合突然出声的尴尬。

6.3 安全卸载与清理

当你不再需要这个功能，或者想彻底清理时，请务必使用项目提供的卸载脚本：

python3 install.py --uninstall

这个操作会尝试从 settings.json 中移除所有它添加的钩子。操作完成后，建议重启一次Claude Code以确保配置生效。

如果卸载脚本执行后出现问题，或者你想进行最彻底的清理，可以手动操作：

1. 关闭Claude Code。
2. 打开终端，输入： cp ~/.claude/settings.json.backup ~/.claude/settings.json 。
3. 删除你克隆的项目文件夹： rm -rf /path/to/claudecode-curry 。

经过几周的深度使用，我个人最大的体会是， claudecode-curry 的成功不在于它有多么复杂的技术，而在于它精准地捕捉到了一个细微但真实的用户痛点——开发者与AI助手交互过程中的“状态盲区”，并用一种极具创意和情感化的方式予以解决。它证明了开发者工具不仅可以高效，还可以有趣、有个性。当你习惯了在代码生成时听到那声“swish”，在任务完成时看到绝杀视频，这些微小的正反馈会实实在在地提升你的开发愉悦感。最后一个小建议是，不妨把它分享给你的开发队友，当你们的Claude Code同时响起库里的解说时，那种会心一笑的默契，也是远程协作中的一点小乐趣。