Turning coding-agent events into a phone status light

I wanted less dashboard, not more

When several coding-agent sessions are running, the expensive question is often very small: which one is still working, which one needs input, and which one finished? Opening every terminal to answer it turns status checking into its own job.

SidePulse is an experiment in ambient state. The phone does not reproduce a transcript. It becomes a set of coloured lights that can be read without changing focus. The value comes from reducing information aggressively enough that the display can sit at the edge of attention.

The text file is a feature

Lifecycle hooks from tools such as Claude Code, Codex, and Kimi feed a small local controller. The controller maps each event to a light state and writes LEDS.TXT. A menu-bar server exposes that file on the local network at /leds.txt.

I chose a plain state file because every boundary is easy to inspect. If the phone shows the wrong colour, I can check the hook payload, the controller output, the file, the HTTP response, and the renderer independently. There is no database or account system to debug before seeing the current state.

The write is atomic: create the new representation, then replace the old one. A reader should see the previous complete state or the next complete state, never half of each.

Local discovery without a setup ceremony

The Mac advertises the service with Bonjour, and the iPhone looks for it on the same local network. The endpoint supplies an ETag so repeated checks can return “unchanged” without sending the body again.

This architecture avoids a hosted relay and keeps the status inside the local network. It also inherits the limits of local networking: guest Wi-Fi isolation, firewall settings, or a sleeping Mac can make discovery fail. SidePulse should report that state clearly rather than displaying an old colour forever.

• Bonjour finds the Mac service on the LAN.
• A tiny HTTP endpoint makes the state easy to inspect.
• ETag avoids retransmitting unchanged state.
• Stale or unreachable state needs a visible disconnected treatment.

Two renderers, one state

The iPhone project contains an eight-light display inspired by ATLD and a smaller two-light side post. They read the same state but answer different physical-layout needs. One can show several sessions; the other can live as a compact signal beside the main screen.

Keeping the transport independent from the renderer made this inexpensive. A new display does not require a new agent integration, and a new lifecycle hook does not require rewriting the iPhone networking layer.

What the source release means here

SidePulse is published as Mac, iPhone, and command-line source. It is not a $29 physical lamp shipped in a box, and the project page now says that directly. Building it yourself is part of the current offer.

That boundary is useful for this stage. People can inspect the event mappings, add a tool, or change what each colour means without waiting for me to operate a hosted service. If the idea evolves, the plain protocol remains a stable place to connect the pieces.