agent-leds replaces the SidePulse Pro's own software with a status light for every coding agent session: Claude Code, Codex, Grok, Cursor, Junie, OpenCode and Pi. All sessions share one queue on the card's eight lights, most urgent at the front: red for an error, orange for a question, blue for a finished turn you have not read, green for working.
- Every agent and every session on one strip, sorted by what needs you most.
- Lights clear themselves: a finished Claude Code session goes dark once you have looked at it in the desktop app, and any session goes dark when its process ends.
- A change that needs you is announced by a snake; anything else settles in quietly.
- Every color looks equally bright on the card.
- The card stays mounted through sleep and locked-screen wakes.
| On the card | |
|---|---|
| A session stops | |
| A session asks a question | |
| A session fails | |
| You read a finished session |
The front of the queue is the light furthest from you, at the right of each picture. macOS only; unofficial and not affiliated with SidePulse.
You need a SidePulse Pro in your Mac's SD slot and Homebrew. Remove SidePulse's own software first: two programs writing to the card overwrite each other.
brew tap mikestopcontinues/tap
brew trust --formula mikestopcontinues/tap/agent-leds
brew install mikestopcontinues/tap/agent-leds
agent-leds installHomebrew 7 installs a formula from a tap only once you trust it, which the second line does for this formula alone.
agent-leds install starts the service at login. The service reads each harness's own session files as they change. Where a harness writes nothing at some moment, such as while Codex waits on an approval, the install adds a hook for that moment alone: Codex, Grok and Cursor get one or two hooks, OpenCode and Pi a plugin of their own, and Claude Code and Junie nothing. It touches only the harnesses you use (~/.claude, ~/.codex, ~/.grok, ~/.cursor, ~/.junie, ~/.config/opencode, ~/.pi), leaves other hooks alone, and removes any of its own that this version no longer uses. Grok's hook makes Grok ask once to trust each folder it starts in other than the home folder, as it does while any hook is registered; grok --trust grants it. Run it again after you start using another harness. After brew upgrade agent-leds the service restarts on the new version by itself; run agent-leds install as well whenever agent-leds doctor then reports a hook or plugin from another version, since a version that hooks the harnesses differently cannot follow their sessions through the old hooks.
If the lights don't follow your sessions, agent-leds doctor says what to fix. It checks the service, the card and the queue the service saved, reads each harness's files the way the service does and says how many sessions are running, and checks each harness's hooks. It writes nothing and does not need the service running.
To remove it, run agent-leds uninstall, then brew uninstall agent-leds.
agent-leds status # the queue
agent-leds doctor # check the install
agent-leds dismiss # clear every light that is not working
agent-leds palette signal # switch palette
agent-leds config # every setting
agent-leds config snake.step_ms 150 # change oneEvery command takes -h; agent-leds config -h lists the settings with their ranges and defaults. Settings live in ~/.config/agent-leds/config.toml, and the log in ~/.local/state/agent-leds/daemon.log.
| Palette | |
|---|---|
default |
|
signal |
|
terminal |
|
neon |
|
ice |
|
colorblind |
|
soft |
Each harness reports a little differently; docs/harnesses.md says what each one shows and where it falls short, and docs/coverage.md lists every signal each one gives.
cargo test && cargo clippy --all-targetsCI runs these, and the workshop's tests, on every push to master on Apple silicon and Intel Macs.
- docs/design.md explains how the service works and lists its open questions.
prototype/is a workshop page for tuning the settings against the card:cd prototype && bun install && bun run dev. It runs whatagent-ledsrenders through the firmware's own interpreter, so it shows what the card will do.bun testthere checks the color model and the rendered programs.bun run previewsinprototype/redraws the pictures above; run it after changing rendering, defaults or palettes.- Pushing a
v*tag releases: dist builds the binaries and updates the Homebrew tap.