RECENT ALERTS

Axol

A tiny axolotl that lives in the corner of your screen, surfaces alerts from any tool that can POST JSON, and cheers you on.

Alerts with a face.

Any tool that can curl can pop her speech bubble. Click to jump back to the terminal, URL, or file that needs you.

A little presence.

Drags anywhere on screen. Nudges you to breathe, hydrate, stretch. Fidgets and naps when things go quiet.

Nothing heavy.

One 350 KB Swift binary. No Electron, no helpers, no telemetry. Idles at 0 % CPU and ~40 MB RAM.

install

macOS only, for now. You'll need the Xcode command-line tools — if xcode-select -p returns a path, you're good; otherwise run xcode-select --install first.

git clone https://github.com/Roach/axol.git
cd axol/axol
./build.sh
./axol

build.sh compiles the Swift sources into a single ~350 KB stripped binary — no Xcode project, no package manager, no code signing. Run NO_STRIP=1 ./build.sh for a debuggable build with symbols, or ./test.sh for the 71-assertion adapter test suite.

Keep her around

Open System Settings → General → Login Items and drag the axol binary into "Open at Login". That's it — no launchctl dance, no helper process. Her window position, size mode, and alert history persist to ~/Library/Application Support/Axol/ across reboots.

What's next

Pick a thread:

View source on GitHub

size modes

⌘-click her to cycle through three sizes: full → mini → micro → full. The current mode persists across launches.

full

~300×360

Default. Bubble above her head; worry bubbles for unresolved alerts.

mini

62×56 → 290×80 with a bubble

Side bubble on her left; blue count badge on her gill.

micro

48×48

Static character + count badge.

send her alerts

Axol listens on 127.0.0.1:47329. Anything you can curl can talk to her — post an envelope from a script, a Makefile, a CI step:

local tool curl · POST
ci-bot · build passed
axol loopback :47329 
curl -s -X POST http://127.0.0.1:47329/ \
  -H 'Content-Type: application/json' \
  -d '{
    "title":    "ci-bot",
    "body":     "build passed on main",
    "priority": "normal",
    "source":   "github-actions",
    "actions":  [{ "type": "open-url", "url": "https://github.com/.../runs/1" }]
  }'

Required field: title. Priority high / urgent floats worry bubbles above her head; urgent also pins the speech bubble open until you handle it. Actions are a closed set — focus-pid, open-url, reveal-file, noop — so there's no shell execution path.

remote alerts optional

Axol's receiver is loopback-only. For services that live on the wider internet — GitHub, Stripe, Sentry — she picks up alerts through a two-part bridge: a signed webhook endpoint in the cloud (the neuromast) and a local 60-line bash forwarder (the lateral line) that drains its queue into the loopback port every 15 seconds.

webhook signed POST
neuromast signed intake
lateral line local forwarder
main · CI passed
feat/nav · review
axol speech bubble
neuromast The cloud half. A signed endpoint that receives a webhook, verifies the signature, and parks the body in a short-TTL queue until the lateral line asks for it. Named after the pressure sensors on a fish's skin.
lateral line The local half. A bash script on your Mac that polls the neuromast every 15 seconds and posts each queued body into Axol's loopback port. Named after the nerve running along a fish's flank that wires those sensors back to her brain.

Set up remote alerts →

plugins

Adapters are JSON files that translate a third-party payload into Axol's envelope. Drop one into ~/Library/Application Support/Axol/adapters/ and anything that POSTs JSON to localhost:47329 can talk to her — no code required.

Plugin reference →