oma
SDK and CLI for building Omarchy shell plugins - one
project, shared logic, multiple surfaces.

Plain JavaScript (TypeScript annotations accepted, stripped at build) is the
logic layer; QML is the UI. Reactive state declared in JS becomes live QML
properties through a generated bridge; plugin config persists automatically to
~/.config/omarchy/<id>.json. The CLI is a single static Go binary with esbuild
embedded - no Node, no Deno, no toolchain required on the user's machine.
Install
Any Linux distro - curl installer:
curl -fsSL https://raw.githubusercontent.com/ussego/oma/main/install.sh | bash
Go:
go install github.com/ussego/oma@latest
Arch Linux - AUR registration is closed, build from the hosted PKGBUILD:
mkdir -p /tmp/oma-bin && cd /tmp/oma-bin
curl -fsSL -O https://raw.githubusercontent.com/ussego/oma/main/packaging/aur/PKGBUILD
makepkg -si
Quickstart
oma create my-plugin # scaffold, directly: oma create my-plugin -s panel -a yourname
cd my-plugin
oma build # bundle src/index.js + generate the QML bridge into ui/
oma install # copy into ~/.config/omarchy/plugins/ and enable
oma restart # install + restart the shell (alias: oma r)
Surfaces: bar, bar-widget, menu, panel, overlay, service - any
combination in one project. oma status shows build/install/launcher state at
a glance; oma skills list ships agent-facing deep dives.
Complete runnable projects live in examples/: counter (bar
widget + attached panel), todo (overlay) and stopwatch (bar widget +
attached panel exercising every runtime feature - state, derived, config, IPC
and actions).
Editor types
Plugin code imports the runtime as import { state, config } from "@oma/runtime" - builds alias it to the runtime embedded in the CLI, so
nothing needs to be installed. For editor intellisense and unit-testing
plugin logic, install the published lib (any package manager):
deno add jsr:@oma/runtime # or: pnpm add jsr:@oma/runtime (10.9+)
npx jsr add @oma/runtime # npm / bun - commit the generated .npmrc
Agent skills
The repo publishes a discovery skill for the open agent skills ecosystem. It
doesn't contain the docs - it routes agents to the installed CLI, which serves
the always-current content (oma skills list, oma skills get <name> [--full]).
npx skills add ussego/oma # project scope - or -g to install once globally
oma create prints this command at the end of scaffolding, and the skill
itself falls back to the curl installer when oma isn't on PATH yet.
Plugin shape
// src/index.js
import { config, state } from "@oma/runtime";
export const music = state({ playing: false, volume: 100 });
export function toggle() {
music.playing = !music.playing;
}
// survives restarts via ~/.config/omarchy/<id>.json - no wiring needed
export const settings = config({ startOnOpen: false });
// ui/Panel.qml - bind to the generated bridge
MusicButton { active: logic.playing; onClicked: logic.toggle() }
Libraries come from node_modules (any package manager); esbuild resolves and
bundles them down to what Quickshell's QJSEngine parses (ES2016).
Development
Building oma itself requires Go 1.27+ only - everything else
(esbuild, TUI deps) is vendored into the module.
# with mise (recommended - see mise.toml)
mise run build # compile dist/oma, callable as `oma` inside the repo
mise run check # gofmt + vet + hermetic tests
mise run live # tier-1 offscreen verification against real Quickshell (safe)
mise run live-shell # tier-2 full round trip - RESTARTS YOUR SHELL
mise run install-dev # symlink dist/oma to ~/.local/bin/oma-dev
# or plain Go from the repo root
go build -trimpath -ldflags "-s -w -X main.cliVersion=dev" -o dist/oma .
go test ./...
Run mise run live after any change to the runtime, bridge template, or
bundler - hermetic tests can't catch QJSEngine-only breakage. Release builds
inject the version via -X main.cliVersion=<tag>; see
.github/workflows/release.yml.
Contributing
Bug reports, feature requests and pull requests are welcome - see
CONTRIBUTING.md for the setup, test conventions and style
rules, and AGENTS.md for the design spec.
Support
oma is free and open source. If it saves you time,
sponsor the project on GitHub ❤️
License
MIT - see LICENSE.