Bbalduzz/nib

build macOS status bar apps in Python.

Summary

Nib is a Python framework for building native macOS menu bar (status bar) apps, with a declarative, SwiftUI-inspired API. The Python process builds a tree of view objects and sends it over a Unix socket to a Swift runtime that renders the actual UI in SwiftUI, then sends interaction events back to Python callbacks.

What it is useful for

Nib targets the gap left by rumps, which the README describes as limited in system integration and customization, with restrictive layout options. Nib is useful when you want a menu bar app that goes beyond a flat list of menu items and includes real controls inside the popover: TextField, Toggle, Slider, Picker, List, ScrollView, Charts, and stacked layouts via VStack/HStack/ZStack. It is also useful when you need system access (notifications, global keyboard shortcuts, clipboard, file/save dialogs, drag and drop) and a built-in settings window with tabs that auto-persists to UserDefaults.

It is also useful when you need to ship a self-contained app: nib build produces a standalone .app bundle in dist/ that includes a portable Python runtime and your dependencies, so the end user does not need a Python installation.

Documented limitation: the README specifies macOS 14+ and Python 3.10+ as requirements, so it is macOS-only and will not work on older macOS releases.

How engineers can use it

Install with pip install pynib (or build from source with git clone https://github.com/Bbalduzz/nib.git && cd nib && make install). Scaffold a project with nib create myapp, then run it in development mode with nib run main.py, which supports hot reload.

The README example sets a status bar icon via nib.SFSymbol("apple.meditate", rendering_mode=nib.SymbolRenderingMode.HIERARCHICAL), defines a custom menu with nib.VStack, nib.Text, nib.MenuDivider, and nib.MenuItem, then builds the popover body with an nib.HStack of nib.Button controls and a counter nib.Text that updates through plain Python callbacks. State is reactive: assigning a new string to count.content re-renders the affected node.

For distribution, nib build main.py produces the .app bundle. Documented flags include --native (compile .py to .so via Cython, requires pip install cython), --obfuscate (strip debug info from .pyc), --no-compile, --icon, --name, and --arch (arm64 or x86_64). Equivalent options can be declared under [tool.nib] and [tool.nib.build] in pyproject.toml. The project is released under the MIT license.