Monitor Codex sessions
Structured parsing distinguishes thinking, tool use, approval, completion, errors and aborted work without uploading the original JSONL file.
A physical status display for CodexCodex Status Light.
Codex Status Light.
Watch every session.
Codex Status Light monitors coding sessions from your Mac menu bar and turns working, tool use, approvals, completion and errors into a glanceable ESP32 LED display—across one Mac or many.
ϟCodex Status3 active sessionsWorking
Storefront APIImplementing checkout validationLED 1
macOS clientRunning xcodebuildLED 2
InfrastructureWaiting for approvalLED 3
One glance. Every session.
How it worksA physical Codex
A physical Codex
status display.
The native macOS app interprets local Codex rollout events and turns them into a stable LED map. Use the Codex Status Light entirely over your LAN or combine several Macs through your own relay account.
Keep every status LED stable
Each active session retains its LED, even when several VS Code windows share the same project or sessions arrive from different Macs.
Choose your privacy boundary
Direct mode stays on your LAN. Relay mode securely aggregates current states from all of your Macs onto one paired Codex Light device.
Local-first
One Mac. One LAN. No account.
The menu-bar app sends complete snapshots straight to codex-light.local. It continues working if the internet disappears.
MacLAN snapshot →Codex Light
Optional relay
Every Mac. One or more lights.
Machine-scoped tokens, TLS and outbound device WebSockets combine sessions without exposing your home network. Pair several lights to mirror the stream or extend two eight-LED devices into 16 session LEDs.
MacsHTTPS →Private relayWSS →Lights
Codex Status Light for macOS
Ready for your menu bar.
Download the signed and notarised universal Codex session monitor for macOS 13 or later. Unzip it, move it to Applications and choose direct LAN mode or the optional multi-Mac relay from Settings.
- 1Download and unzip
- 2Move to Applications
- 3Launch and choose a connection mode
Codex Status LightVersion 0.1.1 · UniversalDownload macOS ZIP17 verified downloads. Downloads are also counted anonymously by this server.ESP32 build guideBuild your own
Build your own
Codex Status Light.
The open hardware is deliberately approachable: an ESP32-WROOM-32, nine WS2812B pixels, an optional OLED and a printable enclosure. Download the STL files, follow the wiring guide and flash the firmware in your browser.
Gather the parts
- ControllerESP32-WROOM-32 development board
- Lights9 × WS2812B pixels
- Optional display128×64 I²C SSD1306 OLED
- Data330–470 Ω resistor
- Power5 V supply + 470–1000 µF capacitor
- Recommended74AHCT125 level shifter
Print the enclosure
Download the STL files, slice them for your printer and print the body and lid. Check fit before fixing the electronics permanently.
Step 3
Wire the light safely
ESP32 GPIO18→330–470 Ω → WS2812B DIN
5 V supply +→WS2812B 5V
5 V supply −→WS2812B GND + ESP32 GND
Capacitor→Across 5V and GND near strip
GPIO21 / GPIO22→Optional OLED SDA / SCL
3V3 / GND→Optional OLED VCC / GND
Common ground is essential. Never power the LED strip through a GPIO pin. Check polarity and data direction before switching on. The optional OLED is detected automatically at 0x3C or 0x3D.
Wiring photos coming next
Add JPG, PNG, WebP or AVIF files to server/wiring-images and they will appear here automatically.
Step 4Use Chrome or Edge on a desktop computer to flash over USB.The browser installer requires this page to use HTTPS. Web flashing requires HTTPS and a browser with Web Serial support. Installing a fresh image erases existing device settings.
Flash the ESP32 in your browser
Connect the ESP32-WROOM board over a data-capable USB cable, open this page in Chrome or Edge on desktop, then select the serial port. The installer writes the tested firmware image directly to the board.
Prefer source?
Build with PlatformIO
cd esp32
~/.platformio/penv/bin/pio run
~/.platformio/penv/bin/pio run -t upload
~/.platformio/penv/bin/pio device monitorThe source uses the Arduino framework. Copy include/secrets.example.h to include/secrets.h only if you want build-time credentials; otherwise use the setup hotspot.
Step 5
Connect it to Wi-Fi
After flashing, join the CodexLight-XXXXXX hotspot using password codexlight. Open http://192.168.4.1/wifi, choose your network and save. The final LED is blue during setup, red while disconnected and green when ready.
Choose direct or relay mode
For direct mode, set the Mac app host to codex-light.local. To combine several Macs, visit http://codex-light.local/relay, give the light a name and approve its pairing code in your dashboard. The published firmware uses the fixed Backends relay address.
Frequently asked questionsCodex Status Light,
Codex Status Light,
explained.
Everything you need to know about the macOS app, ESP32 hardware, privacy and multi-Mac relay before building your own status light.
What is Codex Status Light?
Codex Status Light is a native macOS menu-bar app and build-your-own ESP32 display that turns the current state of Codex coding sessions into stable, glanceable LEDs and optional OLED details.
Does Codex Status Light upload my rollout files?
No. Rollout JSONL files are parsed on each Mac. Direct mode stays entirely on the local network, while optional relay mode sends only bounded session labels, semantic states and timestamps—not raw rollout records.
Can one Codex Light show sessions from several Macs?
Yes. Sign each Mac into the same self-hosted relay account. Pair one or more Codex Light devices to mirror the same stream, or extend two eight-LED devices into one 16-LED session display. The relay preserves separate machine and session identities.
What hardware do I need to build a Codex Status Light?
The reference build uses an ESP32-WROOM-32, eight WS2812B session LEDs, one device-status LED, a suitable 5 V supply, a data resistor and a capacitor. A 128×64 SSD1306 OLED and logic-level shifter are optional.
How do I install the ESP32 firmware?
Use the browser installer in Chrome or Edge over HTTPS, or download the PlatformIO source and flash it over USB. On first start the device creates a protected hotspot for Wi-Fi setup when it cannot reach a saved network.
Is Codex Status Light affiliated with OpenAI?
No. Codex Status Light is an independent project by Backends and is not affiliated with or endorsed by OpenAI.