为 Claude Code 打造桌面状态灯：Arduino 实战

来源：X @eternityspring

将软件程序的内部状态通过物理硬件展现出来，能够带来独特的“仪式感”和直观反馈。本文将指导读者如何利用 Arduino UNO 和一个简单的三色灯模块，为 Claude Code 创建一个桌面状态指示灯，实时显示其空闲、思考和执行状态。

硬件连接

搭建桌面状态灯所需的硬件包括：一块 Arduino UNO 控制板、一个三色灯模块（通常包含 GND、R、Y、G 引脚）、若干杜邦线以及一根 USB 数据线。

具体的接线方式如下：

• Arduino UNO (GND) ──→ 三色灯模块 (GND)
• Arduino UNO (D5) ──→ 三色灯模块 (绿灯)
• Arduino UNO (D6) ──→ 三色灯模块 (黄灯)
• Arduino UNO (D7) ──→ 三色灯模块 (红灯)

请注意，GND 是地线，Arduino UNO 板上有多个 GND 引脚，任选一个连接即可。

Arduino 程序编写

Arduino 的主要任务是监听串口接收到的命令，并根据命令控制三色灯的亮灭或闪烁。程序中约定了如下命令格式：

• G:on：绿灯常亮
• Y:blink:250：黄灯以 250ms 的间隔闪烁
• R:blink:250：红灯以 250ms 的间隔闪烁
• R:on：红灯常亮
• Y:off：黄灯熄灭

将编写好的 Arduino 代码上传到 UNO 板后，可以通过 Arduino IDE 的串口监视器进行初步测试。将波特率设置为 9600，并尝试发送上述命令，确认灯光能够按预期变化，即表示硬件部分连接正常。

电脑端串口桥接机制

直接在每次 Claude Code Hook 触发时打开串口发送命令会导致 Arduino UNO 重启，使灯光显示不稳定。为避免此问题，需要引入一个“常驻桥接”程序来管理串口通信。

建议采用以下结构：

Claude Code Hook -> hook-client.mjs -> 本机 TCP 端口 -> serial-bridge.mjs -> Arduino 串口 -> 三色灯

serial-bridge.mjs 程序将常驻运行并独占 Arduino 串口，Claude Code 的 Hook 只需要将状态发送到这个桥接程序即可。

电脑端脚本配置

电脑端需运行一个常驻的桥接程序，用于接收 Claude Code 的 Hook 命令并转发给 Arduino 串口。完整的开源代码可在 GitHub 仓库 eternityspring/agent-light 中获取。

项目主要包含以下文件：

• serial-bridge.mjs：常驻桥接程序，负责连接 Arduino 串口。
• hook-client.mjs：被 Claude Code Hook 调用以发送状态的客户端脚本。
• lib/commands.mjs：将 Claude Code 的状态名转换为灯光命令的逻辑库。
• claude-settings-snippet.json：Claude Code Hooks 的配置示例片段。

默认的状态映射关系为：

• idle -> G:on (空闲时绿灯常亮)
• thinking -> Y:blink:250 (思考时黄灯每 250ms 闪烁)
• running -> R:blink:250 (执行时红灯每 250ms 闪烁)

启动桥接程序时需要指定 Arduino 连接的串口路径，例如 /dev/cu.usbmodem832101。启动后，也可以通过手动发送测试命令来验证桥接程序是否正常工作。

接入 Claude Code Hooks

Claude Code 支持通过 Hooks 机制在特定事件发生时触发外部动作。本方案利用以下事件来控制状态灯：

• UserPromptSubmit (用户提交指令后)：Claude Code 进入思考状态，黄灯闪烁。
• PreToolUse (工具执行前)：Claude Code 进入执行状态，红灯闪烁。
• PostToolUse (工具执行后)：Claude Code 返回思考状态，黄灯闪烁。
• Stop (回复结束)：Claude Code 返回空闲状态，绿灯常亮。

这些 Hook 配置可以写入项目目录下的 .claude/settings.json 文件中。这种项目级配置的好处是，只有在该项目下启动的 Claude Code 会话才会控制状态灯，不会影响其他项目。

多会话场景处理

当前版本的实现方式是“最后一次状态生效”，即如果多个 Claude Code 会话都配置了 Hook 并向同一个桥接程序发送状态，状态灯将显示最后收到的状态。若需实现更精细的多会话状态聚合，例如“任意会话运行时红灯闪烁”，则需要 Hook 客户端记录每个会话的状态，并根据聚合逻辑控制灯光。

常见问题与解决方案

1. Arduino 程序上传时提示找不到端口：重新插拔 USB 线，并在 Arduino IDE 中选择正确的端口。
2. 串口桥接程序启动失败：确保 Arduino IDE 的串口监视器已关闭，因为串口同一时间只能被一个程序占用。
3. 灯光颜色与预期不符：检查硬件接线与 Arduino 代码中引脚的映射关系。如果实际颜色与代码不一致，可调整代码中的引脚数字。
4. 调整闪烁速度：通过修改命令参数中的毫秒值来调整，例如 Y:blink:500 或 R:blink:100，数字越小闪烁越快。

这个项目虽然技术复杂度不高，但它将抽象的软件状态具象化为桌面上的物理反馈，让编程在视觉和触觉上都多了一份独特的“仪式感”。对于纯软件开发者而言，这种通过代码控制物理硬件的体验，无疑是一种新奇而令人兴奋的成就。