Ranma

Who It's For

Ranma is for developers who want status bar widgets that feel native to macOS but don't want to be locked into a single scripting language or config format. If you've used SketchyBar and wanted something lighter — or if you're already writing shell scripts, Python daemons, or Rust binaries for system monitoring — Ranma lets you wire those scripts directly into the menu bar without wrapping them in a plugin system.

How It Works

Ranma runs a persistent server (ranma-server) that owns a set of floating windows positioned over the macOS menu bar. Each window only covers its content area, so click-through works correctly on uncovered regions. The server communicates over a Unix Domain Socket; you control it entirely through the ranma CLI by sending JSON commands to add, update, or remove named widgets.

The architecture is deliberately split: Rust handles the core logic, state machine, IPC server, and CLI, while Swift/AppKit handles native rendering. This means the UI stays crisp and native while the coordination layer is fast and cross-compilable. Widget nodes are composed from primitives — item, row, column, and box — giving you enough layout flexibility without a full widget framework.

# Start the server
ranma-server &

# Add a widget showing current git branch
ranma add gitbranch --label "$(git branch --show-current)" --icon "sf.arrow.branch"

# Update it from a script loop
while true; do
  ranma set gitbranch --label "$(git branch --show-current 2>/dev/null || echo '-')"
  sleep 5
done

Compared to Alternatives

Compared to SketchyBar, Ranma is younger and has a smaller plugin ecosystem, but its IPC model is more language-agnostic — any process that can shell out can drive it. SketchyBar has a richer built-in event system and more community scripts. Compared to Übersicht, Ranma targets the menu bar specifically rather than desktop widgets, and avoids WebKit overhead by using native AppKit rendering.

Requirements

• macOS version not explicitly documented; targets modern macOS (Apple Silicon and Intel)
• No SIP disable required
• No Accessibility permissions needed
• Early-stage project (v0.1.x) — API may change between releases
• Homebrew tap: typester/ranma

Getting Started

Install via Homebrew, then start the server and add your first widget:

brew install typester/ranma/ranma
ranma-server &
ranma add hello --label "Hello, menu bar"

Widgets persist until you call ranma remove <name> or stop the server. For persistent setups, add ranma-server to your login items or a launchd plist. Full documentation and widget examples are at github.com/typester/ranma.