starlight36/vibecoding-signal-light

Vibecoding Signal Light is a Python project that connects a small physical traffic light, the kind you can buy as a desktop toy or model, to your AI coding agent. While the agent works, the light on your desk changes color to reflect what the agent is doing, so you can tell at a glance whether you need to pay attention without constantly switching back to the terminal. The light states are kept simple. A steady green means the agent is idle. A slow three-color cycle through green, yellow, and red means the agent is actively working. A flashing yellow means the agent needs you to look at something when convenient. A flashing red means deal with it now, typically because the agent is waiting for permission, has hit a block, or has failed. On the hardware side, the reference build uses an MCP2221A USB GPIO adapter, a small board that lets a Mac or Linux machine control physical pins over USB, wired to a three-lamp traffic signal model. The Python code drives the GPIO pins directly, with no cloud service required. Pin assignments and active-low versus active-high wiring can be adjusted via environment variables. The project includes hook adapters for Codex and Claude Code. An install wizard detects which agents are present and installs the right hook entries. When multiple agent sessions are running at the same time, the system aggregates their states so that a red or yellow alert from one session is never hidden by another session starting work. A background worker keeps the light running while the hooks themselves return quickly. A dry-run mode lets you preview all the light states without any hardware connected, which is useful for testing the hook wiring before committing to a physical build.