Developers

Build on QNotch.

Every feature is an extension in its own folder, and the whole app is MIT licensed. Add a card, a tab or a status beside the notch, or just post notifications from a script. Pick the app you build for.

Somafet/qnotch
Open source · MIT

Add your own extension.

QNotch has a shell and sixteen extensions. Each extension keeps its code in one folder. It can add cards, tabs, status segments, search results and settings through the registries below. On the right is the newest one, Weather.

The Mac app is native Swift and AppKit, with its own shell and fifteen extensions. Each extension keeps its code in one folder. It can add cards, tabs, status segments, search results and settings through the registries below. On the right is Weather.

src/QNotch
├─ Shell/            window, pill, panel, tray
├─ Theme/
└─ Modules/
   ├─ ModuleList.cs   the one file that names them
   ├─ Agents/
   ├─ Clipboard/
   ├─ Media/
   ├─ Notifications/
   ├─ Stats/
   ├─ Weather/        the newest, on the right
   ├─ 10 more
   └─ YourExtension/  yours
Modules/Weather/WeatherModule.cs
public sealed class WeatherModule : INotchModule, ICadenceAware
{
    WeatherService? _svc;

    public void Initialize(ModuleContext ctx)
    {
        var s = new WeatherState();
        var set = ctx.Settings.Get<WeatherSettings>("weather");
        var svc = _svc = new WeatherService(ctx, s, set);

        // A wide tile on the Home grid
        ctx.Cards.Register(new CardDescriptor("weather", "Weather", 15,
            () => new WeatherCard(s, svc, ctx.Shell), ColumnSpan: 2));

        // The temperature in the pill
        ctx.Segments.Register(new SegmentDescriptor("weather.pill",
            SegmentSlot.PillRight, 9, () => WeatherSegments.Pill(s)));

        // ...a game bar segment and a settings page, then fetch
        svc.Start();
    }

    // The panel opened: fetch if the forecast expired meanwhile
    public void SetCadence(Cadence cadence)
    {
        if (cadence == Cadence.Fast) _svc?.Wake();
    }
}
src/QNotch.Mac/Sources/QNotchMac
├─ Shell/              notch window, wings, panel, menu bar
└─ Modules/
   ├─ Contracts.swift   the five registries
   ├─ ModuleList.swift  the one file that names them
   ├─ Agents/
   ├─ Clipboard/
   ├─ Media/
   ├─ Notifications/
   ├─ Stats/
   ├─ Weather/          on the right
   ├─ 9 more
   └─ YourExtension/    yours
Modules/Weather/WeatherModule.swift
final class WeatherModule: NotchModule {
    private var context: ModuleContext!
    private(set) var forecast: WeatherForecast?

    func initialize(_ context: ModuleContext) {
        self.context = context
        settings = context.settings.load("weather", default: WeatherSettings())

        // A wide tile on the Home grid
        context.registries.cards.register(ViewContribution(id: "weather",
            title: "Weather", order: 15, symbol: "cloud.sun", span: 2) {
            WeatherCardView(module: self)
        })

        // The temperature beside the notch
        context.registries.segments.register(SegmentContribution(id: "weather.pill",
            order: 9, slot: .trailing) { WeatherPillView() })

        // ...a settings page, then fetch
        start()
    }

    // The panel opened: fetch if the forecast expired meanwhile
    func setVisibility(panel: Bool, activeTab: String) {
        guard panel else { return }
        if let forecast, Date() > forecast.expires { refresh() }
    }
}
  • CardsA tile on the Home grid
  • TabsA page in the panel
  • SegmentsThe pill, the glance strip, the game barThe wings beside the notch
  • Search sourcesResults in the one search box
  • SettingsIts own settings page

Disabled extensions do not load.

Turn off an extension in Settings, Features, then restart QNotch. It will skip that extension at startup, including its timers and hooks. Try the switches below.

Turn off an extension in Settings, Features and it stops right away, timers, listeners and hotkeys included. No restart. Try the switches below.

Contribute an extension.

  1. 1Open an issue

    Say what it does and where it shows: a card, a tab, the pill or the game bar. Space is limited, so agree on that first.

  2. 2Build in your folder

    Everything lives in Modules/<Name>/. One line in ModuleList.cs is the only change outside it.

    Everything lives in Modules/<Name>/. One line in ModuleList.swift is the only change outside it.

  3. 3Snapshot it

    QNotch.exe --snapshot renders every tab and settings page to PNG. CI builds and snapshots every pull request.

    scripts/macos/smoke.sh renders every card, tab and settings page to PNG. CI runs it on every pull request.

  4. 4Send the pull request

    Attach the PNGs and your idle CPU and memory numbers. The performance rules are hard limits.

Post notifications without C#.

Post notifications without Swift.

Send a notification from a build script, hook or scheduled job. Add buttons and read back which button the user clicked.

Notifications reference
Command lineQNotch.exe notify "Deploy done" --app CI --level success
Named pipe\\.\pipe\QNotch.Notify
Local HTTPPOST http://127.0.0.1:47821/notify
Command line, in QNotch.app/Contents/MacOSQNotch notify "Deploy done" --app CI --level success
Unix socket~/Library/Application Support/QNotch.Mac/notify.sock
Local HTTPPOST http://127.0.0.1:47821/notify