What is codex-lamp?

Codex Lamp connects an AI coding tool called Codex to a physical desk lamp, so the lamp's color and animation change automatically based on what the AI is doing at any moment. Codex is a command-line coding assistant, this project adds a visual signal you can notice without looking at your screen. The lamp it works with is a Moonside lamp, which accepts Bluetooth commands to change color, brightness, and animation pattern. When Codex starts or finishes a task, the lamp turns a warm amber. While Codex is actively working, it switches to an animated blue and white pattern. When Codex needs your approval before doing something, the lamp goes purple. Each state maps to a Codex lifecycle event, and you can change the colors or animations to anything the lamp supports. The technical setup is deliberately small. A shell script runs whenever Codex fires a lifecycle hook, and all that script does is write the desired lamp state to a temporary file and make sure a background process is running. The background process, a Python script, holds the Bluetooth connection open and watches that file. When the file changes, the daemon sends the appropriate command to the lamp. Keeping the hook fast and the connection in a separate process means Codex itself is not slowed down by Bluetooth communication. The project requires macOS, Python 3.10 or later, and the Python package bleak for Bluetooth. Setup involves copying two scripts to your Codex home directory and merging a hooks configuration file that tells Codex which events to report. A test script lets you scan for your lamp by Bluetooth name and try color commands manually before hooking it into Codex. Configuration options are set through environment variables and cover things like idle timeout (the lamp turns off after 30 minutes of inactivity by default), the lamp's Bluetooth address (useful if multiple BLE devices are nearby), and the file paths the hook and daemon use to communicate.