Start here

Build extensions for Blipbar: the Mac’s notch as a tiny status bar for everything you keep checking. An extension is a little TypeScript that turns a service (your deploys, your sales, your errors, a game) into blips: live items the notch shows in its ears and its panel, with buttons that act right there.

You write data; Blipbar draws it. Pick a layout (stat, list, progress, session, score, countdown, meter) and a state (idle, running, attention, success, failure, …) and the app’s native renderer does the rest, so your blips look like they shipped with it.

Before you start

You need Blipbar on macOS 15 or later, which you can download from blipbar.app, and Node 22 or later. Hover over the notch or press ⌃⌘B to open it, and right-click it for Settings.

Start one

npm create blipbar-extension@latest my-extension
cd my-extension
npm install
npx blipkit dev

blipkit dev builds as you save and links the folder into Blipbar, which reloads it on every change. The first time, place it: right-click the notch, choose Edit Layout…, and drag it in from the dock underneath. A tool waits under More at the end of the tray, and an extension with only tools needs no placing. Hover over the notch or press ⌃⌘B to open it.

Starters for common kinds of service:

npm create blipbar-extension@latest my-shop -- --template payments   # revenue, sales, MRR
npm create blipbar-extension@latest my-host -- --template deploys    # deploys with time left
npm create blipbar-extension@latest my-errors -- --template errors   # new and returning errors
npm create blipbar-extension@latest my-site -- --template traffic    # visitors, sources, a surge
npm create blipbar-extension@latest my-tracker -- --template tracker # sign-in, your work, an inbox
npm create blipbar-extension@latest my-tool -- --template tool       # a tool in the tray, nothing on a schedule

What one looks like

import { defineExtension, money, stat } from "@blipbar/api";

export default defineExtension({
  async update(ctx) {
    const response = await fetch("https://api.example.com/revenue/today", {
      headers: { Authorization: `Bearer ${ctx.preferences.apiKey}` },
    });
    const { cents, yesterdayCents } = (await response.json()) as { cents: number; yesterdayCents: number };
    ctx.emit(
      stat({
        key: "revenue",
        title: "Revenue today",
        value: money(cents, "USD"),
        reference: money(yesterdayCents, "USD"),
        period: "vs yesterday",
        upIsGood: true,
      }),
    );
    return { nextRunAfter: 300 }; // Blipbar schedules the next run; no timers of your own
  },
});

The manifest lives in package.json under "blipbar": an id (reverse-DNS, like dev.yourname.weather), a title, preferences (a password preference, for an API key, is kept in the Keychain), and the permissions it needs. fetch reaches only the hosts it names, and Node’s own network and process modules are off limits, so fetch and ctx.exec are the only ways out.

The kit

Beyond builders, the package carries what integrations share, so yours reads like Blipbar’s own: sign-in run by the app, Done/Snooze/Mute, a press shown under way, the connection’s trouble said plainly, and four domains with their arithmetic and wording done: payments (revenue against yesterday by now, sales, MRR, disputes, payouts, in every currency’s own decimals), deploys (time left from the usual, stuck builds, Roll back), errors (new, regressed, escalating; spikes), traffic (visitors, sources, a surge).

blipkit

Command	Does
blipkit dev	Build on save, link into Blipbar, and print its log (ctx.log and errors)
blipkit build	Bundle src/index.ts into dist/index.js
blipkit validate	Run update() once against a mock host and check every blip it emits
blipkit pack	Make <name>-<version>.blipbar, one file anyone can open to install it, and print its entry for Blipbar’s directory
blipkit send	Send a blip straight to a running Blipbar
blipkit new	Scaffold an extension (what npm create blipbar-extension runs)

Share it

blipkit pack makes a .blipbar file. Opening it (or Settings › Blips › Install…) shows what the extension is and what it can reach before anything is installed.