# light

**Repository Path**: xzc_share/light

## Basic Information

- **Project Name**: light
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex / Claude Code 信号灯

## 项目背景

这个项目源于一个很具体的小设备:一块 **ESP32-C3 Super Mini** 开发板,外接 **3 个 LED 灯**。

日常使用 Codex、Claude Code 这类 AI 编程工具时,它们经常会在几种状态之间切换:正在工作、等待输入、已经完成、或者遇到错误。单纯盯着终端或编辑器不够直观,所以这个项目想把这些软件里的工作状态,转换成桌面上可以一眼看到的硬件信号。

项目目标是:

- 通过 Codex、Claude Code 的 hook / 脚本感知工作状态
- 把状态发送到本机服务端
- 服务端通过 MQTT 推送给 ESP32-C3
- ESP32-C3 根据状态控制红、黄、绿三个 LED

简单说,它是一个给 AI 编程助手用的实体状态灯。

```
Codex / Claude Code 状态
        |
        | HTTP hook
        v
本机 Go 服务端
        |
        | MQTT
        v
ESP32-C3 Super Mini
        |
        v
红 / 黄 / 绿 LED
```

## 状态含义

三颗 LED 的名称和核心语义:

| LED | 名称 | 核心含义 |
|-----|------|----------|
| 红灯 R | 阻塞灯 | 错误、失败、需要处理、风险 |
| 黄灯 Y | 活动灯 | 正在思考、执行、处理中 |
| 绿灯 G | 就绪灯 | 空闲、完成、可继续 |

固件内部使用虚拟红/黄/绿,物理 GPIO 和点亮极性都可以在配网页配置。当前默认是红灯 GPIO9、黄灯 GPIO6、绿灯 GPIO2,并且低电平点亮(active-low),适合 LED 接 5V、GPIO 拉低点亮的接法。黄绿如果焊反了,可以向控制 topic 发:

```bash
mosquitto_pub -h <broker> -t claude/light -m "ledmap r=9 y=2 g=6"
```

默认通用状态如下:

| 状态 | 含义 | LED 效果 |
|------|------|----------|
| `idle` | 空闲 / 已完成 | 绿灯常亮 |
| `busy` | 正在工作 | 黄灯常亮 |
| `waiting` | 等待用户输入或授权 | 红灯常亮 + 黄灯快闪 |
| `error` | 出错 | 红灯常亮 |
| `done` | 完成提示 | 绿灯慢闪 |
| `off` | 关闭提示 | 三灯全灭 |

项目同时支持来源化状态:

- `claude.*`:Claude Code 的主状态,例如 `claude.busy`、`claude.waiting`、`claude.idle`
- `codex.*`:Codex 的细分生命周期,例如 `codex.prompt`、`codex.tool.bash`、`codex.tool.edit`、`codex.permission`、`codex.stop`

完整 MQTT payload 和更多灯效见 [MQTT_PROTOCOL.md](./MQTT_PROTOCOL.md)。

## 项目组成

- [light.ino](./light.ino):ESP32-C3 固件,负责配网、连接 MQTT、订阅状态消息并控制 LED
- [server](./server):Go 服务端,同时提供 HTTP hook 接口和内置 MQTT broker
- [MQTT_PROTOCOL.md](./MQTT_PROTOCOL.md):ESP32-C3 和服务端之间的 MQTT 消息协议说明
- [server/README.md](./server/README.md):服务端运行、配置和 hook 接入说明

## 使用思路

1. 给 ESP32-C3 Super Mini 烧录 [light.ino](./light.ino)
2. 连接红、黄、绿三个 LED
3. 启动 [server](./server) 里的 Go 服务端
4. 在 Codex 或 Claude Code 的 hook 里调用服务端 HTTP 接口
5. AI 助手状态变化时,桌面信号灯同步变化

服务端默认接收:

```bash
curl -X POST localhost:6660/hook -d busy
curl -X POST localhost:6660/hook -d idle
curl -X POST localhost:6660/hook -d waiting
curl -X POST localhost:6660/hook -d error
```

更完整的运行方式见 [server/README.md](./server/README.md)。