# Show HN: AI Pulse a fake LED strip beside the macOS Dock that shows agent status

> Source: <https://github.com/leog/ai-pulse>
> Published: 2026-08-10 22:07:41+00:00

An ambient macOS light strip for AI coding agents, inspired by the
[SidePulse](https://sidepulse.io/) hardware gadget — but as an app. A slim strip of eight virtual
LEDs floats in the unused space beside the Dock and shows, with a single
aggregate signal and no per-model distinction, whether anything is running,
waiting for you, finished, or broken:

Reduce Motion replaces every animation with a static treatment. The original per-agent icon pill remains available via Settings → Appearance → Indicator style.

AI Pulse is **not** embedded in the Dock — macOS exposes no public API for
Dock accessories. It is a Dock-adjacent, borderless, nonactivating `NSPanel`

positioned from public screen geometry (`NSScreen.frame`

vs `visibleFrame`

).
No private APIs, no Accessibility/Screen Recording permissions, no injection.

Grab `AI-Pulse-<version>.zip`

from the
[latest release](https://github.com/leog/ai-pulse/releases/latest), unzip,
move `AI Pulse.app`

to `/Applications`

, and launch. Releases are not yet
notarized, so on first launch right-click the app → **Open** (on macOS 15+,
also allow it under **System Settings → Privacy & Security → Open Anyway**).
The `aipulse`

CLI ships inside the bundle at
`AI Pulse.app/Contents/Helpers/aipulse`

.

Releases are cut automatically when a PR merges: patch by default, minor or
major when the PR carries a `release:minor`

/ `release:major`

label.

- macOS 14+
- Xcode 16+ / Swift 6 toolchain

```
swift build                         # build everything (app, CLI, kit)
swift test                          # unit + integration tests (AIPulseKit)
swift run AIPulseApp                 # launch the pill (accessory app: no Dock icon)
swift run AIPulseApp --snapshot DIR  # render pill + hover card PNGs headlessly and exit
swift run aipulse health             # CLI: check the local event service
./Scripts/make-app.sh               # assemble + sign dist/AI Pulse.app
./Scripts/make-gifs.sh              # regenerate docs/ GIFs from headless frames (needs ffmpeg)
```

`docs/pulse-social.gif`

is a larger, captioned cut of the same state cycle,
made for sharing.

For day-to-day use, run the bundled app rather than the bare binary: the
script signs it with your Apple Development identity, giving a stable code
signature so the Keychain trusts the app across rebuilds (bare `swift run`

binaries are ad-hoc signed and trigger a Keychain consent prompt after
every rebuild — that is also why `AIPULSE_DEV_EPHEMERAL_TOKEN=1`

exists for
dev loops). The CLI is embedded at `AI Pulse.app/Contents/Helpers/aipulse`

.

(The app product is `AIPulseApp`

because `AIPulse`

and the `aipulse`

CLI would
collide on case-insensitive filesystems.)

AI Pulse listens on `127.0.0.1:7455`

(configurable in Settings). On launch it
stores a bearer token in the Keychain and writes `~/Library/Application Support/AIPulse/cli.json`

(mode 0600) so the `aipulse`

CLI authenticates
without tokens ever appearing in shell commands:

```
aipulse agent upsert \
  --id "claude-code:$PWD:$SESSION_ID" \
  --name "Claude Code" --provider anthropic \
  --instance "$(basename "$PWD")" \
  --state working --message "Implementing Dock placement"

aipulse agent update \
  --id "claude-code:$PWD:$SESSION_ID" \
  --state waitingForInput --message "Waiting for permission" --sequence 2

aipulse agent remove --id "claude-code:$PWD:$SESSION_ID"
aipulse agents        # list everything the pill knows
```

Endpoints: `POST /v1/agents/upsert`

, `POST /v1/agents/{id}/event`

,
`DELETE /v1/agents/{id}`

, `GET /v1/agents`

, `GET /v1/health`

(health is the
only unauthenticated route). The server binds to the loopback interface
only, caps request sizes, validates every payload (`AgentReducer`

+
`RequestValidator`

), rejects unsafe URL schemes, and never executes
anything received in an event.

Dev note: rebuilding the app changes its ad-hoc code signature, so Keychain
reads re-prompt per build; launch with `AIPULSE_DEV_EPHEMERAL_TOKEN=1`

during
development to skip the Keychain and use a per-run token instead.

Quit via the pill's right-click menu → **Quit AI Pulse** (or kill the process).

`Sources/AIPulseKit`

— AppKit-free, fully unit-tested core:`Domain/`

—`Agent`

,`AgentState`

,`AgentAction`

(typed safe actions + URL scheme allowlist),`AgentEventPayload`

(wire model),`AgentIntegrationLevel`

,`StatusPriority`

(urgency sort).`Store/AgentStore`

— single source of truth; all surfaces render from it.`Placement/`

—`ScreenSnapshot`

, best-effort`DockGeometry`

inference, pure`PlacementPolicy`

(gutter → adjacent → corner fallbacks, clamping).

`Sources/AIPulse`

— the app:`Presentation/Pill/`

— nonactivating`AIPulsePanel`

, SwiftUI capsule, per-state icons (glyph + badge + ring, never color alone), hover card.`Presentation/AgentList/`

,`Presentation/Settings/`

— conventional keyboard-accessible windows.`Placement/DockPlacementController`

— debounced screen-change observation; no polling.

Milestones 1–3 are complete:

-
**M1**— nonactivating panel, pill UI, mock agents, hover card, context menu. -
**M2**— bottom/left/right Dock placement, multi-display selection with a Settings display picker, debounced screen/space-change observation, off-screen clamping, opt-in auto-hidden-Dock following (best-effort, from the Dock's public preference domain — read-only, no Dock interaction). -
**M3**—`AgentReducer`

event normalization (versioning, ID validation, sequence/timestamp ordering, duplicate rejection, safe-action mapping), centralized`StalenessPolicy`

(working agents stale after a configurable silence, then demoted to disconnected after a longer one; agents whose backing process has exited are demoted within one sweep via a PID liveness check; completed agents expire after a configurable delay; waiting, approval, and failed states never expire on timers), and persistence to`~/Library/Application Support/AIPulse/agents.json`

with restart restore: unresolved attention states come back as-is, live-only states come back as`disconnected`

until their source reports again. -
**M4**— loopback-only HTTP event service (`LocalHTTPServer`

), Keychain bearer token + 0600 handshake file for the CLI, transport validation, the`aipulse`

publisher CLI, and end-to-end integration tests. Verified live: CLI → HTTP → reducer → store → pill in ~150 ms round-trip. -
**M5**— Claude Code adapter (`ClaudeCodeAdapter`

+`aipulse claude-hook`

), built against the documented hook lifecycle: SessionStart→idle, UserPromptSubmit/PreToolUse→working, PermissionRequest and permission-prompt Notifications→approvalRequired, idle-prompt Notifications→waitingForInput, Stop→completed, StopFailure→failed, SessionEnd→removed. One pill entry per session per project. Prompt text, tool inputs, and assistant output are never decoded, so they can never be published. The hook always exits 0 and prints nothing. -
**M6**— optional dynamic Dock icon (off by default; Settings → Appearance). Aggregates the same AgentStore snapshot as the pill via`DockTileAggregator`

: failure > attention > working > neutral, with an`NSDockTile`

custom content view for the state treatment and`badgeLabel`

showing the count of unacknowledged urgent agents. The floating pill and the Dock icon are independently toggleable; the icon never bounces.

All six MVP milestones are complete, followed by the pivot to the
lights-first presentation (`LightAggregator`

+ `LightStripView`

), keeping
the icon pill as an option.

This repository ships `.claude/settings.json`

registering `aipulse claude-hook`

for the relevant hook events (via the debug build path), so
Claude Code sessions in this repo appear in the pill automatically once the
app is running. For system-wide use:

```
swift build -c release
sudo cp .build/release/aipulse /usr/local/bin/
```

then register the same hooks in `~/.claude/settings.json`

, replacing the
command with plain `aipulse claude-hook`

. Claude Code asks you to approve
project hooks the first time it loads them.

AI Pulse displays status sent by local agent integrations. It does not read prompts, terminal contents, editor contents, or application windows.

Contributions are welcome — see [CONTRIBUTING.md](/leog/ai-pulse/blob/main/CONTRIBUTING.md) for the
project's design principles, testing expectations, and how to add a new
agent integration. [docs/DEBUGGING.md](/leog/ai-pulse/blob/main/docs/DEBUGGING.md) covers the
debugging surface: environment variables, headless snapshots, log
streaming, on-disk state, and fixes for the common failure modes.