Process plugin

Output

Text with optional symbols, colours, and visibility, streamed by an external process as newline-delimited JSON. The executable runs directly with its arguments and inherits the bar’s environment. There is no default execution timeout; plugins are long-running streams.

Example

{
  "id": "plugin",
  "type": "plugin",
  "plugin": {
    "executable": "/absolute/path/to/provider",
    "arguments": [],
    "restart": true,
    "maxLength": 80,
    "onError": "keepLast"
  }
}

Replace the executable with your provider’s path. ${NAME} and ~ expand in the executable path. Set restart: false for a one-shot provider.

Configuration

Use the item-level text template to customise or hide the label. The provider options below control its data, symbols, colours, and visibility.

All fields below are inside plugin.

Input protocol

Every new process receives this JSON line first on stdin:

{ "version": 1, "event": "start" }

Runtime triggers follow, with an optional value:

{ "version": 1, "event": "refresh", "value": { "source": "manual" } }

The input mailbox holds up to 32 events and drops new events when full. Each restart creates a fresh mailbox with start first. Queued events from the previous process are discarded; triggers during restart backoff or after a one-shot exit are dropped.

Output protocol

Emit one JSON object per line on stdout, terminate every message with a newline, and flush after each update. stderr is discarded.

{
  "text": "3 updates",
  "symbol": "shippingbox.fill",
  "tint": "#FFCC00",
  "hidden": false
}

Each message replaces the previous result. Omitted optional fields reset their result-level values. A result glyph must include its own font, for example {"glyph":"X","font":"Menlo","size":14}. Display text collapses whitespace into a single line and truncates to maxLength with an ellipsis.

State appearance and errors

Symbol precedence is item-level symbol, configured state symbol, then result symbol. No symbol appears if none is supplied. Configured glyphs inherit plugin.symbols.font and optional size, with per-glyph overrides; see font glyph symbols. SF Symbols use symbolFontWeight. showSymbol: false hides every symbol source.

Configured state tints override the result tint, which otherwise overrides normal item/theme styling. Colours accept #RRGGBB or #RRGGBBAA.

A new process starts with running appearance and the previous successful result, or … if none exists. Valid output uses success appearance. Launch, protocol, and nonzero-exit failures use failure appearance and the selected error policy. Retained results keep their symbol, tint, and hidden state, subject to state overrides. A clean one-shot exit retains its last result.

To change plugin, edit the configuration file. sbar set cannot change this block.

Shared item options cover styling, symbols, actions, priority, and enabled state.

Text templates

The item-level text setting supports id, value, symbol, status, error. See text templates for syntax and field meanings. value keeps the plugin’s truncation and error policy. Templates cannot look up arbitrary JSON result fields. Streamed text is literal data, not a template.

Updates

Plugins stream updates regardless of the item refresh policy. Runtime triggers are offered to running plugins, subject to mailbox limits. When output arrives faster than the bar can display it, the bar keeps only the latest result in its one-result buffer. See refresh policies.

Automatic restarts back off from one to 30 seconds. A run lasting at least 30 seconds that emitted valid output resets the delay to one second. On reload, only plugins whose executable, arguments, or restart setting changed are restarted; appearance changes preserve the process.

Removing or disabling a plugin, or shutting down the bar, terminates its process group. Updates from an obsolete process cannot overwrite its replacement or failure state.

Current limits

Each JSON line is limited to 64 KB excluding its terminating newline. Malformed, oversized, or unterminated messages stop the process with an explicit error. The bar discards stderr. Trigger delivery follows the queue and restart rules above.