SidePulse

From agent event to visible signal

SidePulse listens to lifecycle hooks from supported coding tools, translates those events into a tiny LED state, and writes the result atomically to a local LEDS.TXT file. The Mac component serves that state over the local network; the iPhone app renders it as either an eight-light ATLD-style display or a compact two-light side post.

The deliberately small output is the point. A coloured light can answer “is it working, waiting, or done?” from across the room without opening another dashboard or keeping the terminal in view.

• Lifecycle hooks for Claude Code, Codex, and Kimi workflows.
• A local controller with atomic state-file writes.
• Bonjour discovery and an HTTP /leds.txt endpoint with ETag support.
• Two iPhone renderers: eight LEDs or a two-LED side post.

A local, inspectable architecture

The state is intentionally plain enough to inspect with ordinary tools. The phone reads a small local-network endpoint rather than depending on a hosted account, and the components are published so a developer can audit or change the mapping for a different workflow.

Atomic writes prevent the phone from reading a partially updated state file. HTTP caching through ETag avoids transferring the same value repeatedly while keeping the polling model easy to reason about.

Software, not bundled hardware

SidePulse is a software project inspired by physical agent-status lights. It uses a phone screen as the display, so the repository does not include or ship a dedicated LED device.

The open-source repository includes the Mac app, iPhone app, and command-line pieces. The Mac companion now has a one-command source installer; the iPhone app still needs to be built with the user’s own Apple signing team.