Wiring Codex CLI Notifications to a Desk Light
Three domed lenses in red, amber and green sit on the matte-black Status Light. Codex CLI can call an external notification program, but the light's own catalogue information does not confirm a programmable interface.
How does Codex CLI hand events to your script?
Current official OpenAI documentation defines a user-level notify configuration as an array containing the executable and its fixed arguments. Codex invokes that program for supported events and appends one JSON argument. Notification configuration belongs in the user's main config file because project-scoped Codex configuration cannot override the notify key.
The only external notify event currently documented is agent-turn-complete. Its common fields include the event type, thread and turn identifiers, working directory, input messages and last assistant message. Validate the type and tolerate missing or future fields.
What should the notify script do with them?
Parse the single JSON argument without evaluating it as shell text. For the supported completion type, write a compact local record containing thread, working directory, turn and update time. Return quickly and let a separate worker handle slow network or hardware operations.
Do not copy full prompts or assistant text into logs by default. Those fields may contain source code, secrets or private instructions. Use identifiers and a safe project label for the ambient signal, then protect the state file from other users.
How do you map Codex events to light states?
With the currently documented external event, the honest mapping is narrow: a completed agent turn can set a ready-for-review state. It does not prove tests passed, changes are correct or the task is finished. It also does not provide an external notify event for every approval request or failure.
Use unknown while the adapter is unavailable and clear ready state when a person returns to the thread. Additional red or amber meanings require separate verified sources, such as a test wrapper or another documented event channel.
What are the limits of this wiring?
Codex TUI notifications and the external notify command are related but different. The built-in TUI can filter certain interface events and can use terminal notification methods, while external notify currently has the documented completion event. Do not assume the two expose identical payloads.
The Status Light supplies the visible lenses, not a confirmed API or electrical protocol. Test the Codex script with saved JSON, malformed input and concurrent threads. Only then add a hardware worker for an interface verified on the actual unit. Keep notification code outside untrusted project directories and reference an absolute reviewed path. Log only parse failures and safe identifiers. After changing the user configuration, run one harmless Codex turn and confirm exactly one event arrives before enabling any persistent worker.