SidePulse

Setup & user guide

SidePulse Pro fits a MacBook Pro SD slot. SidePulse Dot works with USB-C on Mac, Linux, Windows, iPhone, and compatible Android phones (beta). On a computer, the lights change when you write a text file to the device. The macOS software makes agent status automatic.

1. Plug it in

SidePulse Pro — SD card slot

1. Hold the card with the gold contacts facing down and going in first, and the LED edge facing you.
2. Push it into the SD slot of your 14" or 16" MacBook Pro in one smooth, firm motion, all the way until it stops.
3. Give it a few seconds. A small SidePulse drive appears in Finder and the LEDs light up.

One decisive push. Pushing the card halfway, pausing, and then pushing the rest of the way can leave it undetected: the Mac sees the contacts land in two stages and gives up. If nothing shows up, pull the card straight out and insert it again in a single motion.

To remove it, eject the SidePulse drive in Finder, then pull the card straight out. It can stay in permanently; the software keeps it mounted through sleep and lock.

SidePulse Dot — USB-C

1. Plug it into a USB-C port on a Mac, Linux or Windows computer, a USB-C iPhone, or a compatible Android phone (beta). It fits either way up.
2. On Mac, Linux and Windows, it mounts as a small SidePulse drive. Write LEDS.LED to control the lights directly.
3. On an iPhone, install the SidePulse iOS app, currently in beta: join on TestFlight or build it from GitHub. The dot is driven from your Mac over push notifications, so it works even with the phone locked.
4. On Android, the beta SidePulse app supports local patterns and USB playback. Remote agent updates need a compatible bridge and setup.

2. Install the software

One command, on macOS. Paste it into Terminal:

curl -fsSL https://sidepulse.io/setup.sh | sh

If macOS offers to install the command line developer tools, say yes; the installer needs Python 3.10 or newer, which they include. Run the same command again any time to upgrade.

What it does:

• Installs the sidepulse command into ~/.local/bin inside its own isolated environment.
• Installs the agent hooks for Claude Code, Codex, Cursor, Junie and Grok, so the LEDs follow your coding agents automatically.
• Installs the menu-bar app and enables it at login.
• Installs eject prevention for SidePulse Pro, so the card stays mounted after sleep or lock.

Check that it works:

sidepulse write "#30d158 800ms pulse\nrepeat"   # green breathing
sidepulse write off

Prefer to do it by hand? The device is just a file:

echo "#30d158 800ms pulse" > /Volumes/SidePulse*/LEDS.LED

Both apps are open source: the sidepulse CLI and the SidePulse iOS app are on GitHub. The iOS app is in beta on TestFlight.

3. Using it

• Agent status. Nothing to do. While an agent is working the LEDs roll cyan, they pulse amber when it needs you, and settle green when it is done.
• Menu bar. Click the SidePulse icon to see recent sessions, jump to an agent, or switch the LEDs between agent status and battery.
• Battery status. In the menu bar, open SidePulse, find your device, and select Battery Level.
• Lid closed. The menu-bar app can keep the Mac awake while agents run and let it sleep when they finish. Enable it in Settings.
• iPhone. Run sidepulse link on your Mac, scan the QR code with the SidePulse app, then sidepulse push "#30d158 pulse" --title "Done" reaches the Dot in your pocket. Shortcuts works too.
• Your own scripts. Anything that can write a text file can drive the lights. The animation language is documented in the LED format reference; all commands are in the README.

Eject prevention. macOS unmounts the SD reader when the Mac sleeps or locks, which would leave SidePulse Pro dark until you reinsert the card. The installer adds a small helper that keeps the card mounted. If you skipped it, run sidepulse setup again or install it from the menu-bar app's Setup window. It is not needed for SidePulse Dot.

Troubleshooting

• The Pro card is not detected. Pull it out and reinsert it in one decisive push, all the way in. Try a different orientation only if it does not go in easily; never force it.
• The card disappears after sleep or lock. Run sidepulse setup again, or open the menu-bar app's Setup window and install Eject Prevention.
• sidepulse: command not found. Add ~/.local/bin to your PATH, or call it as ~/.local/bin/sidepulse.
• LEDs stay dark. Make sure the drive is mounted (ls /Volumes), then write off followed by a program. Programs are limited to 512 bytes and 20 lines.
• Something else. Email peter@inteliwear.xyz, ask on Discord, or open an issue on GitHub.

Care

Keep the device dry and away from heat. Do not bend the Pro card or force either device into a port. Not a toy: small parts, keep away from small children. Nothing inside is user-serviceable.

Regulatory information