Agent Lightstrip Controller

A proof-of-concept Yeelight LAN controller that will later bridge agent runtime states to lightstrip colors.

Overview

This repository provides:

• A minimal Yeelight LAN client (yeelight_lan.py)
• Predefined color/animation effects mapped to Claude Code & Codex hook events (effects.py)
• A hook listener CLI (hook_listener.py) that receives hook payloads and drives the lightstrip
• A simple CLI for ad-hoc color changes (set_color.py)

Requirements

• Python 3.10+
• A Yeelight lightstrip (tested with Lightstrip 1S / S1) with LAN control enabled in the Yeelight app. The lightstrip and the host running this script must share the same local network.

Usage

pip install -r requirements.txt
python -m src.set_color --host <YOUR_LIGHTSTRIP_IP> --hex ff00ff

This will ensure the strip is on, then transition to the specified color.

Future updates will add state listeners for Devin/Codex agents and map their lifecycle to colors.

Tests

pip install -r requirements.txt
PYTHONPATH=src pytest

CI is configured via GitHub Actions to run the same command on pushes and pull requests.

Hook listener (Claude Code / Codex)

The module src.hook_listener bridges hook payloads to the lightstrip:

PYTHONPATH=src python -m src.hook_listener --host 192.168.2.123 --event UserPromptSubmit

When Claude Code invokes a command-type hook, the payload (JSON via stdin) must contain hook_event_name. Example hook configuration in .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "PYTHONPATH=/path/to/agent-lightstrip/src python3 -m hook_listener --host 192.168.2.123"
          }
        ]
      }
    ],
    ...
  }
}

• The listener resolves the event name, looks up the effect in EVENT_EFFECTS, and drives the lightstrip accordingly.
• Pass --default-hex to show a fallback color for unmapped events.
• Use --dry-run to inspect the resolved effect without touching the lamp.

Codex 也支持同名事件（参考 https://developers.openai.com/codex/hooks）。在 ~/.codex/config.toml 或项目 .codex/config.toml 中添加命令 hooks，例如（详见 examples/codex-config.sample.toml）：

[[hooks.UserPromptSubmit]]
matcher = ""
  [[hooks.UserPromptSubmit.hooks]]
  type = "command"
  command = "PYTHONPATH=/path/to/agent-lightstrip/src python3 -m hook_listener --host 192.168.2.123"

[[hooks.PermissionRequest]]
matcher = "Bash|apply_patch"
  [[hooks.PermissionRequest.hooks]]
  type = "command"
  command = "PYTHONPATH=/path/to/agent-lightstrip/src python3 -m hook_listener --host 192.168.2.123"

[[hooks.Stop]]
  [[hooks.Stop.hooks]]
  type = "command"
  command = "PYTHONPATH=/path/to/agent-lightstrip/src python3 -m hook_listener --host 192.168.2.123"

• matcher 可按需限制工具类型（如只针对 Bash）。
• Codex hook 也会将事件 JSON 传入 stdin，并使用工作目录运行命令。
• 若要手动触发（无 Hook），仍可通过 --event 指定事件名称。

Roadmap & Contribution Ideas

• Add reconnection retries when the Yeelight socket closes unexpectedly
• Persist latest known state to avoid redundant commands
• Provide Docker-compose or systemd unit samples for long-running services
• Expand effect mappings to more hook events or custom workflows

References

• Yeelight LAN Protocol
• Claude Code Hooks
• Codex Hooks

Contributions via issues and pull requests are welcome.

License

MIT License

---

项目简介（中文）

agent-lightstrip 是一个把智能灯带与 AI Agent 状态联动的示例项目，核心特性包括：

• yeelight_lan.py：实现 Yeelight 局域网协议的最小客户端。
• effects.py：预设多种颜色/动画效果，并与 Claude Code、Codex 的 Hook 事件匹配。
• hook_listener.py：作为命令型 Hook 的监听器，读取 stdin 中的 JSON 事件并控制灯带。
• set_color.py：命令行工具，可指定颜色直接点亮灯带。

环境要求

• Python 3.10 以上
• Yeelight S1（或支持 LAN Control 的 Yeelight 灯带），需在 Yeelight App 中开启“局域网控制”。
• 运行脚本的主机与灯带需在同一局域网。

快速上手

pip install -r requirements.txt
python -m src.set_color --host <YOUR_LIGHTSTRIP_IP> --hex ff00ff

Hook 集成说明

1. Claude Code：在 ~/.claude/settings.json 中配置 hooks（参考 examples/claude-settings.sample.json），将事件如 UserPromptSubmit、PermissionRequest 等指向 hook_listener.py。
2. Codex：在 ~/.codex/config.toml 或项目 .codex/config.toml 添加命令 hook，结构与官方文档一致。

Hook 触发时会把 JSON 事件通过 stdin 传给 hook_listener，程序根据 EVENT_EFFECTS 中的映射驱动灯带。

改进方向

• 增加 Yeelight 连接失败时的重试与重连机制。
• 编写更完善的日志输出，方便排查网络中断或响应异常。
• 支持多灯带或多房间同步展示（通过配置文件或 MQTT 转发）。
• 与更多 Agent 生态集成（如 Devin 自定义 CLI、其他自研 Agent 平台）。

参考资料

• Yeelight LAN Protocol
• Claude Code Hooks
• Codex Hooks

欢迎提交 Issue 或 PR 一起完善项目。