AI Pulse

An ambient macOS light strip for AI coding agents. Eight virtual LEDs beside your Dock show, at a glance, whether anything is running, waiting on you, finished, or broken.

Download for macOS View on GitHub

macOS 14+ · free and open source (MIT) ·

One signal, six states

No per-model distinction and no counters — one aggregate signal across every agent you have running. Each state is a distinct animation, and each is also distinguishable without relying on color alone.

Working

A cyan comet streaks while an agent runs.

Needs you

Breathes orange when an agent waits for input or approval.

Failed

Double-blinks red when a session breaks.

Finished

All eight settle to solid green.

Idle

A slow aurora drifts while sessions sit quiet.

Off

Dark when nothing is connected.

Reduce Motion replaces every animation with a static treatment. A per-agent presentation — one LED per session instead of one aggregate strip — is available under Settings → Appearance → Indicator style.

Lives beside the Dock

The strip floats in the unused space next to the Dock — visible while you work, out of the way when you don't need it.

A macOS desktop with the Dock at the bottom center and AI Pulse animating a cyan comet in the empty space to its right
AI Pulse is not embedded in the Dock — macOS exposes no public API for Dock accessories. It is a Dock-adjacent, borderless, nonactivating panel positioned from public screen geometry. No private APIs, no Accessibility or Screen Recording permissions, no injection.

Install

  1. Download AI-Pulse-<version>.zip from the latest release and unzip it.
  2. Move AI Pulse.app to /Applications and launch it.
  3. 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. Building from source needs macOS 14+ and an Xcode 16 / Swift 6 toolchain — see the README.

Settings

Right-click the pill → Settings… to adapt AI Pulse to your setup.

The AI Pulse settings window, showing the Placement, Appearance, Behavior, State priority, Local API, and Privacy sections
Tap to view full size.
Placement
Which side of the Dock the pill sits on, which display it follows (automatic tracks the Dock's display), the corner it falls back to when there is no room beside the Dock, and whether it follows an auto-hidden Dock off-screen.
Appearance
Indicator style switches between Lights (one aggregate strip for all agents) and Agent lights (one LED per session, so every agent's state is visible at once). Pill background picks the capsule: Dark, Translucent, or Transparent — lights floating straight over the wallpaper. The floating pill and the Dock icon toggle independently; the Dock icon carries a numeric badge for agents needing attention and a dot while agents work.
Behavior
Housekeeping timers: when completed agents leave the pill, when silent working agents are dimmed as stale, and when they are demoted to disconnected. Waiting, approval, and failed states never expire — they stay until resolved or acknowledged.
State priority
Most important first. With agents in different states, the strip and Dock icon show the highest state present, and per-agent lights sort in this order — which also decides who stays visible when there are more agents than slots. Put Working on top if you'd rather see in-progress work than finished runs, or reset to the default.
Local API
The loopback port integrations publish to — see wiring up your agents.
Privacy
A reminder of the contract: AI Pulse only renders status events. It never reads prompts, terminals, editors, or windows.

Wire up your agents

AI Pulse listens on 127.0.0.1:7455. Anything that can make a local HTTP request can drive the strip.

Claude Code

Register aipulse claude-hook in your Claude Code settings and sessions appear on the strip automatically.

pi

Drop the bundled aipulse-pi.ts extension into ~/.pi/agent/extensions/ and reload.

Anything else

Push state from any script with the aipulse CLI or the loopback HTTP API.

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 "..." --state waitingForInput --sequence 2
aipulse agent remove --id "..."
aipulse agents        # list everything the strip knows

On launch AI Pulse stores a bearer token in the Keychain and writes ~/Library/Application Support/AIPulse/cli.json (mode 0600), so the CLI authenticates without tokens ever appearing in shell commands.

Privacy

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

The server binds to the loopback interface only, caps request sizes, validates every payload, rejects unsafe URL schemes, and never executes anything it receives.