Skip to content

About

Status lights for coding agents on a SidePulse Pro, replacing its own software

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

agent-leds

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 blue snake crosses the strip and the queue rises with blue at the front A session stops
An orange snake crosses the strip and the queue rises with orange at the front A session asks a question
A red snake crosses the strip and the queue rises with red at the front A session fails
A wave runs along the queue and the blue light leaves 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.

Install

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 install

Homebrew 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.

Use

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 one

Every 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 default
signal signal
terminal terminal
neon neon
ice ice
colorblind colorblind
soft 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.

Development

cargo test && cargo clippy --all-targets

CI 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 what agent-leds renders through the firmware's own interpreter, so it shows what the card will do. bun test there checks the color model and the rendered programs.
  • bun run previews in prototype/ 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.

About

Status lights for coding agents on a SidePulse Pro, replacing its own software

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages