# Vee

> A native, leak-free macOS menu-bar script runner, compatible with the
> xbar and SwiftBar plugin protocol. Plugins are ordinary executables that
> print text (or JSON) to standard output; Vee runs them on a schedule and
> renders the result as menu-bar titles, dropdown menus, and native widgets.

The complete documentation is also available as a single document:
[https://vee.navbytes.io/llms-full.txt](https://vee.navbytes.io/llms-full.txt).

## Documentation

- [Getting started](https://vee.navbytes.io/guide/getting-started.md): Install Vee, write your first plugin, and learn where plugins live. A native macOS menu-bar script runner, xbar and SwiftBar compatible.
- [Migrating from SwiftBar / xbar](https://vee.navbytes.io/guide/migrating-from-swiftbar.md): Move to Vee from SwiftBar or xbar in one step: point it at your existing plugins folder. Full protocol compatibility, plus a trust layer and typed SDK.
- [Plugin authoring](https://vee.navbytes.io/guide/plugin-authoring.md): The full Vee plugin reference: filenames and intervals, menu structure, line parameters, metadata headers, SF Symbols, ANSI, Markdown, streaming, and cron.
- [Widgets](https://vee.navbytes.io/guide/widgets.md): Render Vee plugins as native desktop and Notification Center widgets: the surface contract, the widget card schema, the five templates, and the composable layout tree.
- [Trust model](https://vee.navbytes.io/guide/trust-model.md): How Vee makes plugins transparent: authors declare what they touch with <vee.*> tags, and Vee shows a plain-language trust summary before install. Advisory, not a sandbox.
- [Preferences](https://vee.navbytes.io/guide/preferences.md): Plugins declare typed settings with <xbar.var>; Vee auto-generates a form and stores secrets in the macOS Keychain. Configuration belongs to the plugin.
- [Plugin SDKs](https://vee.navbytes.io/guide/sdk.md): Zero-dependency Vee plugin SDKs for TypeScript, Python, and Go — the same typed Menu/Section builders in every language, producing byte-identical output.
- [JSON output](https://vee.navbytes.io/guide/json-output.md): Vee's optional structured-JSON output format: opt in with a top-level {"vee":1} object, skip the text protocol's quoting and escaping, and get typed items and clean nesting.
- [CLI & URL actions](https://vee.navbytes.io/guide/cli-and-urls.md): Run Vee from source with swift run vee, and drive it at runtime with vee:// and swiftbar:// URL actions — refresh, enable/disable, toggle, and notify.
- [Debugging & testing](https://vee.navbytes.io/guide/debugging.md): Preview, watch, and lint a Vee plugin without installing it: vee render, vee show, vee dev, and vee lint, plus execution timeouts, exit codes, and the Debug console.
- [Writing plugins with an LLM](https://vee.navbytes.io/guide/writing-plugins-with-an-llm.md): Hand a model the whole plugin format in one file, give it the JSON Schemas instead of prose, and close the loop with vee lint — plus the mistakes to watch for.
- [Custom plugin stores](https://vee.navbytes.io/guide/enterprise-store.md): Point Vee at your own curated plugin catalog: a GitHub repo, a static HTTP host, or an air-gapped file mirror, with integrity checks and MDM-managed configuration.
- [FAQ](https://vee.navbytes.io/guide/faq.md): Answers about Vee: is it safe un-sandboxed, will my SwiftBar/xbar plugins work, macOS 26 and Apple Silicon requirements, where secrets are stored, and more.
- [Troubleshooting](https://vee.navbytes.io/guide/troubleshooting.md): Fix common Vee issues: a plugin not appearing, Gatekeeper blocks, timeouts, missing interpreters and PATH differences, and refreshes not happening.

## Machine-readable contracts

- [Widget card schema](https://vee.navbytes.io/schemas/widget-card.schema.json): JSON Schema for the payload a plugin prints in widget mode, including the layout tree. Validated in CI against the SDKs' golden fixtures.
- [JSON output schema](https://vee.navbytes.io/schemas/json-output.schema.json): JSON Schema for the structured-JSON alternative to the text protocol.

## Optional

- [Plugin SDKs](https://github.com/navbytes/vee/tree/main/plugins): zero-dependency TypeScript, Python, and Go builders that emit byte-identical output.
- [Example plugins](https://github.com/navbytes/vee/tree/main/examples): runnable, heavily commented showcase plugins.