Writing plugins

Bar and launcher load third-party widgets as .so files. A plugin does not draw pixels. It emits Surface Description nodes through a small C ABI, and the host renders them. User-facing install, enable toggles, and the example plugins: Plugins. This page is the write-your-own side. otter-shell already ships otter-shell-plugins (examples) and otter-plugin-factory (opf). You can also install them on their own:

pikman install otter-shell-plugins otter-plugin-factory

Layout and discovery

Packed plugins look like this:

/usr/lib/otter-shell/plugins/<id>/
  plugin.conf
  libotter_plugin_<snake_id>.so

Hosts search in this order. First match per id wins:

OTTER_PLUGIN_PATH (colon-separated roots)
$XDG_DATA_HOME/otter-shell/plugins
~/.local/share/otter-shell/plugins
/usr/lib/otter-shell/plugins
/usr/share/otter-shell/plugins

Bar and launcher layout names are always plugin:<id>. The bare id lives in plugin.conf. Enable gates live in ~/.config/otter-shell/plugins.conf as <id>_enabled = true|false. Hosts read that file before dlopen. Most plugins treat a missing key as enabled. The packaged snippet-provider is opt-in and defaults to disabled. Per-plugin files under ~/.config/otter-shell/plugins/<id>.conf are reserved for schemas with provides_settings = true. That settings UI is not in yet.

Manifest (`plugin.conf`)

id = "hello-label"
name = "Hello label"
version = "0.1.1"
abi_version = 1
library = "libotter_plugin_hello_label.so"
provides_bar_widget = true
provides_launcher_provider = false
provides_launcher_sd_rows = false
provides_settings = false

Factory CLI (`opf`)

otter-plugin-factory is a separate package from the examples. After install, opf is on PATH. From a checkout, put bin/ on PATH instead.

opf new bar-widget my-chip
opf new launcher-provider my-provider

cd my-chip
opf build
opf pack                 # zig-out/plugins/<id>/{plugin.conf,.so}
opf check                # manifest + otter_plugin_* exports

Copy zig-out/plugins/<id>/ into ~/.local/share/otter-shell/plugins/ or set OTTER_PLUGIN_PATH. Factory docs/publishing.md covers the examples-package layout.

ABI v1

Plugins export C symbols. Zig plugins can @import a mirrored otter_plugin_abi module. ABI major is OTTER_PLUGIN_ABI_VERSION (1). Required exports:

Symbol	Role
`otter_plugin_abi_version`	Must return `1`
`otter_plugin_init` / `otter_plugin_deinit`	Lifetime
`otter_plugin_query`	Fill `OtterPluginManifest`

Bar, when provides_bar_widget is true:

otter_plugin_bar_attach returns an OtterPluginBarInstance with a vtable
Vtable: preferred_width, contribute, destroy, optional on_event

Launcher, when provider or SD-row flags are set:

otter_plugin_launcher_query / otter_plugin_launcher_activate
Optional otter_plugin_launcher_contribute_row for custom SD rows

Host API during contribute:

sd_rect / sd_label / sd_hit_button
Optional sd_text_input for IME-backed fields. Null-check on older hosts.
request_frame, log

BarVTable.on_event can receive click, hover, focus/blur, and text-input (buffer/preedit flags). Headers and Zig mirrors live in otter-bar, otter-launcher, and otter-shell-plugins (include/otter_plugin_abi.h, abi/abi.zig).

Examples in `otter-shell-plugins`

Layout id	Host	What it shows
`plugin:hello-label`	bar	Smallest click chip. `on_event` toggles Hello and Clicked.
`plugin:bar-search`	bar	`sd_text_input` plus text-input-v3 IME (preedit, commit, focus)
`plugin:cmd-watch`	bar	Interval command to a label
`plugin:disk-free`	bar	`statfs` free space plus a usage bar
`plugin:idle-inhibit`	bar	logind idle inhibit toggle on click
`plugin:snippet-provider`	launcher	Results provider plus custom SD rows

hello-label

Smallest SD chip that gets a real click from the host: bar_input_dispatch to the plugin slot to BarVTable.on_event(CLICK). Left click toggles the label text (Hello / Clicked) and background tint, then calls host.request_frame. No side-channel file.

# otter-bar.conf
layout_right = plugin:hello-label, clock

bar-search

Bar text field using host sd_text_input with Wayland text-input-v3. Focus the field, type, and confirm IME preedit/commit. Escape blurs. $XDG_RUNTIME_DIR/otter-bar-search is fallback only on old hosts.

layout_center = plugin:bar-search

Local development

git clone https://git.pika-os.com/otter-shell/otter-shell-plugins.git
cd otter-shell-plugins
zig build -Doptimize=ReleaseFast pack
export OTTER_PLUGIN_PATH="$PWD/zig-out/plugins"

ABI smoke, no Wayland:

zig build -Doptimize=ReleaseFast plugin-abi-smoke -- zig-out/plugins/hello-label/libotter_plugin_hello_label.so

Bar plugins: use otter-bar’s zig build -Doptimize=ReleaseFast plugin-abi-smoke -- <so>.

Trust

Installed .so plugins are fully trusted and share the host process. Ship examples through otter-shell-plugins, or load plugins you built yourself.

otter-shell-plugins: examples package source
otter-plugin-factory: opf CLI and agent skills
otter-zenith: Debian packaging
otter-bar / otter-launcher: host runtimes

Getting Started

Libraries

Layout and discovery

Manifest (`plugin.conf`)

Factory CLI (`opf`)

ABI v1

Examples in `otter-shell-plugins`

hello-label

bar-search

Local development

Trust

​Layout and discovery

​Manifest (plugin.conf)

​Factory CLI (opf)

​ABI v1

​Examples in otter-shell-plugins

​hello-label

​bar-search

​Local development

​Trust

​Related repos

Layout and discovery

Manifest (`plugin.conf`)

Factory CLI (`opf`)

ABI v1

Examples in `otter-shell-plugins`

hello-label

bar-search

Local development

Trust

Related repos