Quickstart

Anywhere, with Node 22 or later:

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

(Use npm create blipbar-extension, not npx blipkit new, to start one: blipkit on npm is someone else’s package. Inside a project npx blipkit finds @blipbar/api’s own.)

npm create blipbar-extension runs blipkit new, which scaffolds package.json (with a manifest, TypeScript and Node’s types to check with), src/index.ts, and tsconfig.json. It also writes AGENTS.md (and a CLAUDE.md that points to it), which tells whichever AI helps build it where these guides are and the rules it tends to trip on, and fills in the manifest’s author from git. --template tool starts a tools-only one instead. Its id is dev.<you>.<name>; pass --id to choose one (a domain of yours, reversed) before anyone installs it: the id is how Blipbar knows it, and its settings and saved keys go by it. blipkit dev builds in watch mode and symlinks the folder into ~/Library/Application Support/Blipbar/Extensions/<id>. The host watches that folder and reloads your extension on every change. That’s the whole loop: edit, save, watch it update live in the notch.

The first time, place it, since an extension runs only while it’s placed: right-click the notch, choose Edit Layout…, drag your extension from the dock underneath into an ear or the panel, and press Done. A tool waits under More at the end of the tray, where + keeps it in the tray; an extension with only tools needs no placing. To open the notch, hover over it or press ⌃⌘B.

The generated src/index.ts:

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

export default defineExtension({
  async update(ctx) {
    ctx.emit(
      stat({
        key: "value",
        title: "My Extension",
        icon: "bolt.fill",
        value: number(0),
      }),
    );
    return { nextRunAfter: 30 };
  },
});

Replace the stat(...) with real data (a fetch, a computed value, anything), pick whichever layout fits (Builders: one per layout), and you have a working extension.