[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80726":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":29,"discoverSource":30},80726,"vibecoding-signal-light","starlight36\u002Fvibecoding-signal-light","starlight36","A real traffic light for AI agents.","",null,"Python",95,18,43,2,0,3,26,52,17,3.84,false,"main",true,[],"2026-06-12 02:04:06","# Vibecoding Signal Light\n\n> A real traffic light for AI agents.  \n> 给 AI Agent 一个看得见的状态灯。\n\nVibecoding Signal Light turns a small red\u002Fyellow\u002Fgreen traffic signal model into an ambient status display for Codex, Claude Code, and other local AI coding agents. When the agent is working, waiting, blocked, or asking for permission, the light on your desk changes with it.\n\nIt is deliberately simple: glance at the lamp, know whether you should keep flowing or look back at your agent.\n\nVibecoding Signal Light 把一个红、黄、绿三色交通信号灯模型变成 AI 编程助手的实体状态面板。Codex、Claude Code 或其他本地 Agent 开始工作、请求权限、遇到阻塞时，桌上的信号灯会同步变化。\n\n它的目标不是炫技，而是让 AI Agent 从屏幕里的文字流，变成房间里能被一眼感知的工作伙伴。\n\n## Demo \u002F 示例\n\n![Vibecoding Signal Light demo: green idle state mounted beside a laptop](docs\u002Fimages\u002Fdemo.jpg)\n\nThe reference build mounted beside a laptop, showing the steady green idle state.\n\n参考实物安装在笔记本旁边，图中是绿灯常亮的空闲状态。\n\n## Why This Exists \u002F 为什么做这个\n\nAI coding agents are getting more autonomous, but their state is still trapped inside a terminal or chat window. That creates two awkward modes:\n\n- You keep checking the agent too often and break your own focus.\n- You forget it is waiting for permission, a result review, or a failure recovery.\n\nThis project gives the agent a physical presence:\n\n- Green means you can relax.\n- A slow three-color cycle means the agent is busy.\n- Yellow means the agent explicitly needs a look.\n- Red means stop what you are doing and unblock it.\n\nAI 编程助手越来越能自己跑命令、改文件、开子任务，但它的状态通常还困在终端或聊天窗口里。于是你要么反复切回去看，打断自己的注意力；要么忘了它正在等权限、等你读结果、或者已经失败。\n\n这个项目给 Agent 一个真实存在的环境信号：\n\n- 绿灯：没事，继续你的事。\n- 绿黄红慢速循环：Agent 正在工作。\n- 黄闪：Agent 明确需要你看一眼或继续。\n- 红闪：需要马上处理，通常是权限、阻塞或失败。\n\n## Hardware \u002F 硬件\n\nThe current reference build uses:\n\n| Part | Description |\n| --- | --- |\n| MCP2221A USB GPIO adapter | Drives the traffic light from a Mac\u002FLinux machine over USB |\n| 3-light traffic signal model | Red, yellow, and green LEDs or lamp modules |\n| Python + EasyMCP2221 | Local GPIO control, no network service required |\n\n当前参考硬件：\n\n| 硬件 | 说明 |\n| --- | --- |\n| MCP2221A USB GPIO 转接板 | 通过 USB 从电脑控制 GPIO |\n| 三色交通信号灯模型 | 红、黄、绿三路 LED 或灯模块 |\n| Python + EasyMCP2221 | 本地控制 GPIO，不需要额外云服务 |\n\nDefault wiring is active-low:\n\n| Signal | MCP2221A pin | Meaning |\n| --- | --- | --- |\n| Green | `gp0` | Idle |\n| Yellow | `gp1` | Attention |\n| Red | `gp2` | Permission, blocked, or failed |\n| Active level | GPIO `LOW` | Light on |\n\n默认接线是低电平点亮：\n\n| 灯 | MCP2221A 引脚 | 含义 |\n| --- | --- | --- |\n| 绿灯 | `gp0` | 空闲 |\n| 黄灯 | `gp1` | 需要关注 |\n| 红灯 | `gp2` | 权限、阻塞或失败 |\n| 有效电平 | GPIO `LOW` | 灯亮 |\n\n### Wiring \u002F 接线\n\nThe reference build uses a common-anode, active-low LED-style wiring. Each light has its own current-limiting resistor unless your traffic light module already includes one.\n\n参考实物使用公共正极、低电平点亮的 LED 接法。每一路灯都应该串联独立限流电阻，除非你的交通灯模块已经内置电阻。\n\n```text\nMCP2221A 3.3V  ────────────────┬── Green LED anode \u002F 绿灯正极\n                               ├── Yellow LED anode \u002F 黄灯正极\n                               └── Red LED anode \u002F 红灯正极\n\nGreen LED cathode \u002F 绿灯负极   ── 220Ω-1kΩ ── GP0\nYellow LED cathode \u002F 黄灯负极  ── 220Ω-1kΩ ── GP1\nRed LED cathode \u002F 红灯负极     ── 220Ω-1kΩ ── GP2\n```\n\n```mermaid\nflowchart LR\n    V33[\"MCP2221A 3.3V\"] --> COMMON[\"Common anode \u002F 公共正极\"]\n    COMMON --> GLED[\"Green LED \u002F 绿灯\"]\n    COMMON --> YLED[\"Yellow LED \u002F 黄灯\"]\n    COMMON --> RLED[\"Red LED \u002F 红灯\"]\n    GLED --> GR[\"220Ω-1kΩ\"] --> GP0[\"GP0\"]\n    YLED --> YR[\"220Ω-1kΩ\"] --> GP1[\"GP1\"]\n    RLED --> RR[\"220Ω-1kΩ\"] --> GP2[\"GP2\"]\n```\n\nIn this mode, the MCP2221A GPIO pin sinks current:\n\n- GPIO `HIGH`: light off\n- GPIO `LOW`: light on\n\n这种模式下 MCP2221A GPIO 负责下拉电流：\n\n- GPIO `HIGH`：灯灭\n- GPIO `LOW`：灯亮\n\nIf your signal model is common-cathode or active-high, wire each GPIO through a resistor to the LED anode, connect the cathodes to `GND`, and set:\n\n```bash\nexport SIGNAL_LIGHT_ACTIVE_LOW=0\n```\n\n如果你的灯是公共负极或高电平点亮，则应让每个 GPIO 通过限流电阻接到对应 LED 正极，LED 负极接 `GND`，并设置：\n\n```bash\nexport SIGNAL_LIGHT_ACTIVE_LOW=0\n```\n\nImportant: MCP2221A GPIO pins are for small LED loads only. If your traffic light uses 5V\u002F12V lamps, LED strips, relays, or anything above the GPIO current limit, use a transistor, MOSFET, relay module, or dedicated LED driver between the MCP2221A and the light.\n\n注意：MCP2221A GPIO 只适合直接驱动小电流 LED。若你的信号灯是 5V\u002F12V 灯组、灯带、继电器，或电流超过 GPIO 能力，请在 MCP2221A 和灯之间增加三极管、MOSFET、继电器模块或专用 LED 驱动。\n\nYou can override the wiring:\n\n```bash\nexport SIGNAL_LIGHT_GREEN_PIN=gp0\nexport SIGNAL_LIGHT_YELLOW_PIN=gp1\nexport SIGNAL_LIGHT_RED_PIN=gp2\nexport SIGNAL_LIGHT_ACTIVE_LOW=1\n```\n\nSet `SIGNAL_LIGHT_ACTIVE_LOW=0` if your traffic light is wired active-high.\n\n## Lamp Language \u002F 灯语\n\nThe language is intentionally small and persistent. The current light should always describe the current state.\n\n灯语刻意保持简单，并且状态会持续显示。你不需要记复杂动画，只要看当前灯效。\n\n| Light \u002F 灯效 | Agent state \u002F Agent 状态 | Human action \u002F 你该做什么 |\n| --- | --- | --- |\n| Steady green \u002F 绿灯常亮 | Idle \u002F 空闲 | Nothing \u002F 不用管 |\n| Slow green-yellow-red cycle \u002F 绿黄红慢速循环 | Working \u002F 正在思考、跑工具、改文件或测试 | Wait \u002F 等它跑 |\n| Flashing yellow \u002F 黄灯闪烁 | Explicit attention \u002F 明确需要你读结果或继续 | Look when convenient \u002F 有空看一眼 |\n| Flashing red \u002F 红灯闪烁 | Permission, blocked, or failed \u002F 需要权限、阻塞或失败 | Look now \u002F 马上处理 |\n| Off \u002F 全灭 | Manual clear \u002F 手动清除 | Nothing \u002F 不用管 |\n\nThe work cycle avoids software PWM on plain GPIO hardware, because USB GPIO timing can create visible flicker. On the MCP2221A reference build, the work state is a calm, slow three-color cycle. If you later add a driver that supports real brightness control, the same pattern can be rendered as a soft pulse.\n\n当前 MCP2221A GPIO 参考实现不会用软件 PWM 模拟呼吸灯，因为 USB GPIO 的时序抖动会造成肉眼可见的频闪。工作态默认是安静的三色慢速循环。如果未来换成真正支持亮度控制的驱动，同一套模式可以渲染成柔和脉冲。\n\n## Features \u002F 功能亮点\n\n- Physical ambient status for AI agents.\n- Codex hook adapter.\n- Claude Code hook adapter.\n- Session-aware aggregation for multiple concurrent agent sessions.\n- Red and yellow alerts are never hidden by another session starting work.\n- Background worker keeps animations persistent while hooks return quickly.\n- Dry-run mode for testing without hardware.\n- Environment-based GPIO mapping for custom builds.\n\n- 给 AI Agent 一个实体环境状态灯。\n- 支持 Codex hook。\n- 支持 Claude Code hook。\n- 支持多个 Agent 会话并发时的状态聚合。\n- 红灯\u002F黄灯告警不会被另一个会话的工作态覆盖。\n- 后台 worker 保持灯效持续运行，hook 本身快速返回。\n- 支持无硬件 dry-run 预览。\n- 支持通过环境变量调整 GPIO 接线。\n\n## Quick Start \u002F 快速开始\n\nInstall dependencies with your preferred Python workflow. With `uv`:\n\n```bash\nuv sync\n```\n\nList the signal language:\n\n```bash\n.\u002Fscripts\u002Fsignal-light list\n```\n\nPreview without hardware:\n\n```bash\n.\u002Fscripts\u002Fsignal-light play working --dry-run\n.\u002Fscripts\u002Fsignal-light play attention --dry-run\n.\u002Fscripts\u002Fsignal-light play permission --dry-run\n```\n\nRun a wiring test on the real MCP2221A setup:\n\n```bash\n.\u002Fscripts\u002Fsignal-light test\n```\n\nPlay real signals:\n\n```bash\n.\u002Fscripts\u002Fsignal-light play working\n.\u002Fscripts\u002Fsignal-light play permission\n.\u002Fscripts\u002Fsignal-light play idle\n```\n\nThe wrapper scripts avoid writing `__pycache__` files in the repository. By default they use `.venv\u002Fbin\u002Fpython` when it exists, then fall back to `python3`. If you want wrappers to run through `uv`, set:\n\n```bash\nexport SIGNAL_LIGHT_USE_UV=1\n```\n\n## Codex Integration \u002F Codex 集成\n\nThe easiest way to install or repair local hooks is the built-in wizard:\n\n```bash\n.\u002Fscripts\u002Finstall-hooks\n.\u002Fscripts\u002Finstall-hooks --all -y\n.\u002Fscripts\u002Finstall-hooks --agent codex --agent claude-code -y\n```\n\nThe wizard detects supported local agents, validates the current hook files, creates timestamped backups, and installs only the Signal Light hook entries while keeping other hooks on the same events.\n\n安装或修复本地 hook 最简单的方式是内置向导：\n\n```bash\n.\u002Fscripts\u002Finstall-hooks\n.\u002Fscripts\u002Finstall-hooks --all -y\n.\u002Fscripts\u002Finstall-hooks --agent codex --agent claude-code -y\n```\n\n向导会识别已支持的本地 Agent，检查当前 hook 文件，写入前创建带时间戳的备份，并且只安装 Signal Light 自己的 hook 条目，保留同一事件下已有的其它 hook。\n\nCodex hooks can call the wrapper with the event name:\n\n```bash\n.\u002Fscripts\u002Fcodex-signal-hook UserPromptSubmit\n.\u002Fscripts\u002Fcodex-signal-hook PreToolUse\n.\u002Fscripts\u002Fcodex-signal-hook PermissionRequest\n.\u002Fscripts\u002Fcodex-signal-hook Stop\n```\n\nRecommended hook mapping:\n\n| Codex event | Signal behavior |\n| --- | --- |\n| `SessionStart` | Green idle |\n| `UserPromptSubmit` | Working cycle |\n| `PreToolUse` | Working cycle |\n| `PostToolUse` | Working cycle |\n| `PermissionRequest` | Red flashing |\n| `Stop` | Clear normal working state |\n| `SessionEnd` | Brief green completion blink, then current aggregate state |\n\nSee [docs\u002FLAMP_LANGUAGE.md](docs\u002FLAMP_LANGUAGE.md) for a complete `~\u002F.codex\u002Fhooks.json` example.\n\nCodex hook 可以直接把事件名传给 wrapper：\n\n```bash\n.\u002Fscripts\u002Fcodex-signal-hook UserPromptSubmit\n.\u002Fscripts\u002Fcodex-signal-hook PreToolUse\n.\u002Fscripts\u002Fcodex-signal-hook PermissionRequest\n.\u002Fscripts\u002Fcodex-signal-hook Stop\n```\n\n推荐映射：\n\n| Codex 事件 | 灯效行为 |\n| --- | --- |\n| `SessionStart` | 绿灯空闲 |\n| `UserPromptSubmit` | 工作循环 |\n| `PreToolUse` | 工作循环 |\n| `PostToolUse` | 工作循环 |\n| `PermissionRequest` | 红灯闪烁 |\n| `Stop` | 清理普通工作态 |\n| `SessionEnd` | 绿灯短闪提示完成，然后恢复当前聚合状态 |\n\n完整 `~\u002F.codex\u002Fhooks.json` 示例见 [docs\u002FLAMP_LANGUAGE.md](docs\u002FLAMP_LANGUAGE.md)。\n\n## Claude Code Integration \u002F Claude Code 集成\n\nClaude Code sends hook data as JSON on stdin, so the wrapper usually needs no event argument:\n\n```bash\necho '{\"event\":\"PreToolUse\",\"session_id\":\"demo\"}' | .\u002Fscripts\u002Fclaude-code-signal-hook\necho '{\"event\":\"PermissionRequest\",\"session_id\":\"demo\"}' | .\u002Fscripts\u002Fclaude-code-signal-hook\necho '{\"event\":\"Notification\",\"session_id\":\"demo\"}' | .\u002Fscripts\u002Fclaude-code-signal-hook\n```\n\nSupported Claude Code events include:\n\n| Claude Code event | Signal behavior |\n| --- | --- |\n| `SessionStart` | Green idle |\n| `UserPromptSubmit` | Working cycle |\n| `PreToolUse` | Working cycle |\n| `PostToolUse` | Working cycle |\n| `PostToolUseFailure` | Red flashing |\n| `Notification` | Yellow flashing |\n| `PermissionRequest` | Red flashing |\n| `Stop` | Clear normal working state |\n| `SessionEnd` | Brief green completion blink, then current aggregate state |\n\nClaude Code 会通过 stdin 传入 JSON hook 数据，因此 wrapper 通常不需要额外参数：\n\n```bash\necho '{\"event\":\"PreToolUse\",\"session_id\":\"demo\"}' | .\u002Fscripts\u002Fclaude-code-signal-hook\necho '{\"event\":\"PermissionRequest\",\"session_id\":\"demo\"}' | .\u002Fscripts\u002Fclaude-code-signal-hook\necho '{\"event\":\"Notification\",\"session_id\":\"demo\"}' | .\u002Fscripts\u002Fclaude-code-signal-hook\n```\n\n支持的 Claude Code 事件包括：\n\n| Claude Code 事件 | 灯效行为 |\n| --- | --- |\n| `SessionStart` | 绿灯空闲 |\n| `UserPromptSubmit` | 工作循环 |\n| `PreToolUse` | 工作循环 |\n| `PostToolUse` | 工作循环 |\n| `PostToolUseFailure` | 红灯闪烁 |\n| `Notification` | 黄灯闪烁 |\n| `PermissionRequest` | 红灯闪烁 |\n| `Stop` | 清理普通工作态 |\n| `SessionEnd` | 绿灯短闪提示完成，然后恢复当前聚合状态 |\n\nSee [docs\u002FLAMP_LANGUAGE.md](docs\u002FLAMP_LANGUAGE.md) for a complete `~\u002F.claude\u002Fsettings.json` example.\n\n完整 `~\u002F.claude\u002Fsettings.json` 示例见 [docs\u002FLAMP_LANGUAGE.md](docs\u002FLAMP_LANGUAGE.md)。\n\n## Multi-Session Behavior \u002F 多会话行为\n\nThe runtime stores the latest state for each agent session and shows the highest-priority aggregate on the physical light:\n\n```text\nred flashing > yellow flashing > working cycle > steady green\n```\n\nThat means one session waiting for permission will stay red even if another session starts working. A normal `Stop` only clears non-urgent working state; it does not erase an existing red alert.\n\nWhen one tracked session ends while other sessions are still running, the runtime briefly flashes green as a completion cue, then restores the current aggregate state. If all sessions have ended, it settles on steady green. Red or yellow alerts are not interrupted by this completion cue.\n\n运行时会记录每个 Agent 会话的最新状态，并把最高优先级状态显示到真实信号灯上：\n\n```text\n红灯闪烁 > 黄灯闪烁 > 工作循环 > 绿灯常亮\n```\n\n因此，一个会话正在等待权限时，即使另一个会话开始工作，红灯也不会被覆盖。普通 `Stop` 只会清掉非紧急的工作态，不会误清除已有红灯告警。\n\n当某个已记录的会话结束、但其它会话还在运行时，运行时会让绿灯短暂闪烁，提示“有一个会话完成了”，然后恢复当前聚合状态。如果所有会话都结束了，最终会回到绿灯常亮。红灯或黄灯告警不会被这个完成提示打断。\n\n## Project Status \u002F 项目状态\n\nThis is a small, hackable hardware companion for AI-assisted development. It is designed to be easy to fork, rewire, and adapt:\n\n- Swap MCP2221A for another GPIO backend.\n- Add true PWM or LED strip drivers.\n- Map other agent systems into the same lamp language.\n- Build a nicer enclosure and put it on your desk.\n\n这是一个小而可改的 AI 编程硬件伴侣项目。你可以很容易地 fork 并扩展它：\n\n- 把 MCP2221A 换成其他 GPIO 后端。\n- 增加真正的 PWM 或灯带驱动。\n- 把更多 Agent 系统映射到同一套灯语。\n- 做一个更漂亮的外壳，把它放到桌面上。\n\nIf your AI agent has become part of your workflow, give it a signal light.\n\n如果 AI Agent 已经成了你的工作流的一部分，给它一盏真正的状态灯。\n","Vibecoding Signal Light 是一个为 AI 编程助手设计的实体状态灯，通过红、黄、绿三色灯光直观展示 AI 代理的工作状态。该项目利用 Python 和 EasyMCP2221 库实现本地控制，无需额外网络服务。硬件方面主要由 MCP2221A USB GPIO 转接板和三色交通信号灯模型组成，支持在 Mac\u002FLinux 平台上运行。适合需要与 AI 编程助手协作但又不想频繁切换窗口打断工作流的开发者使用。通过这种直观的状态指示，用户可以更轻松地判断何时需要介入处理，从而提高工作效率。","2026-06-11 04:01:48","CREATED_QUERY"]