Vee

A native, leak-free macOS menu-bar script runner.

Vee runs plugins — any executable, in any language — on a schedule and renders their stdout natively. One script can be a menu-bar item, a Notification Center widget, a searchable panel, and a window on your desktop; rows pick their own surfaces with visibleOn=. AppKit throughout, no WebView, no third-party dependencies, and a plain-language trust summary that shows what a plugin touches before you install it. Existing xbar and SwiftBar plugins run unchanged.

📖 Documentation · 🌐 vee.navbytes.io

Install

macOS 26+ on Apple Silicon. Developer-ID-signed and notarized. One binary is both the menu-bar app and the vee CLI, so installing gets you both.

brew install --cask navbytes/tap/vee

Or without Homebrew:

curl -fsSL https://vee.navbytes.io/install.sh | bash

Other routes (direct download, mise for the CLI only) and the installer's options: Getting started.

Your first plugin

A plugin's filename encodes its refresh interval — name.INTERVAL.ext. Drop hello.5s.sh into ~/Library/Application Support/Vee/plugins:

#!/bin/bash
echo "Hello 👋"
echo "---"
echo "It works!"
echo "Refresh | refresh=true"

chmod +x it. The line above --- is the menu-bar title; everything below is the dropdown. Full reference: Plugin authoring.

Already have xbar or SwiftBar plugins? Point Vee at your existing folder (Plugin Manager → Choose Folder) — that is the whole migration.

Documentation

Getting started	Install, first plugin, the basics.
Plugin authoring	The full text protocol: params, submenus, headers, surface targeting (visibleOn=), streaming, cron.
JSON output	The recommended format for new plugins — typed, no |-quoting.
SDK migration guide	Porting a plugin off the retired official SDKs.
Rich params & charts	progress=, sparkline=, pie/donut/stacked-bar, toggle=, slider=.
Widgets	Notification Center tiles and the Vee Health roll-up.
Preferences	Declared plugin variables become typed settings forms; secrets in the Keychain.
Trust model	<vee.*> declarations and the install-time trust summary.
CLI & URL actions	vee render, vee lint, vee dev, vee new, vee://.
Migrating from SwiftBar/xbar	What carries over, and what does not.
Custom plugin stores	Run Discover against your own catalog, signed and pinned.
Troubleshooting · FAQ	When something does not work.
Architecture · Contributing	For contributors.

If vee.navbytes.io is blocked on your network, the same docs are mirrored at vee-docs.pages.dev.

Ready-to-run examples live in plugins/showcase/ — including kitchen-sink.1m.sh, one file exercising every JSON field.

Build from source

swift build && swift test
swift run vee                   # run the menu-bar app for development

The distributable bundle is xcodegen generate && xcodebuild -project Vee.xcodeproj -scheme Vee build. Module layout and design notes: ARCHITECTURE.md.

Contributing & license

Contributions are welcome — see CONTRIBUTING.md. Vee is open source under the MIT License.