The widget store for Omalauncher, the Android launcher that runs Arch Linux and draws home-screen widgets written in OWL, a small declarative widget language. It also holds OWL faces, whole home pages, and OWL apps: full-screen views that open from the app drawer instead of sitting on a page.
Everything in widgets/, faces/ and apps/ has been reviewed. When a pull request is merged, CI builds
index.json (widgets), faces.json (faces) and apps.json (apps) and publishes the store to GitHub Pages, where the
launcher's store reads them. Before installing, it shows you every command a widget or app runs
and every package it installs, and it checks the download against the reviewed file's SHA-256.
The easy way: long-press your widget on the phone and tap publish. Your coding agent forks this repo with the GitHub CLI and opens the pull request for you.
By hand:
-
Fork this repo and add your widget at
widgets/<your GitHub username, lowercase>/<name>/widget.owl. Names use lowercase letters, digits and dashes. -
Give it
metaand declare its packages:widget "disk" { meta { description: "Free space on the root disk"; version: "1.0"; license: "MIT"; category: "system" } size: 3x2 requires { pacman: ["dua-cli"] } ... } -
Optionally add
preview.png, a screenshot of the tile (under 300 KB). For the store to show the tile in the user's own Omarchy theme, addpreviews/<theme>.webptoo, one per theme (under 100 KB each, named liketokyo-night.webp); the launcher's debug build makes them withscripts/store-previews.sh. This goes for faces and apps as much as widgets: anything that uses theme colors (accent,foregroundand the rest) getspreviews/, not onlypreview.png. -
Check it locally:
java -jar tools/owl.jar review . widgets/<you>/<name>/widget.owl -
Open a pull request. The review check runs the same rules and writes a summary of what the widget runs and installs; a maintainer reviews it and merges.
The widget language is documented in docs/LANGUAGE.md.
An app is an OWL file that starts with app "name" { } instead of widget: the nodes at its top
are the whole full-screen view, and it has no tile, so no size. It goes at
apps/<your GitHub username, lowercase>/<name>/app.owl, follows the same steps and rules as a
widget, needs meta { owl: 8 }, and should have an icon: an SVG in the file, drawn in
currentColor so it takes the user's theme accent, or a PNG embedded as an asset. The launcher
shows it standalone on the theme's background; see the Apps section of the launcher's widget
README for the style the store's apps share. A game or a view with a header of its own can leave
the window's title row out with title: ""; launchers before that show an empty title row instead:
app "notes" {
meta { owl: 8; description: "Quick notes that stay on the phone"; version: "1.0"; license: "MIT"; category: "productivity" }
title: "notes"
icon: """<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round">
<path d="M11 5h18l9 9v29H11z"/>
<path d="M29 5v9h9M17 24h15M17 32h10"/>
</svg>"""
state notes = [] persist
Column {
Input { placeholder: "write a note…"; clear: true; onSubmit: notes = [value] + notes }
for n in notes { Text { text: n } }
}
}Check it with java -jar tools/owl.jar review . apps/<you>/<name>/app.owl. Its previews are
pictures of the whole view at a phone's size, which scripts/store-previews.sh makes too. An app that
uses theme colors gets previews/<theme>.webp like a widget, not only preview.png. A widget
and an app can't share a name. Launchers from before apps (0.7.2 and older) only read index.json, so they never see one.
A face is a whole home page, as a watch face is a watch's whole screen: an OWL file that starts with
face "name" { }. Its nodes fill the screen, with no tile and no size, and it sits left of page 1
where a stock launcher has its feed. It goes at faces/<your GitHub username, lowercase>/<name>/face.owl,
follows the same steps and rules as a widget and needs meta { owl: 10 }. statusBar: false hides
the status bar; see the Faces section of the launcher's widget README:
face "quiet" {
meta { owl: 10; description: "The time, large, and nothing else"; version: "1.0"; license: "MIT"; category: "time" }
source now = clock every 1m
Column {
align: center
Text { text: fmtTime(now, "HH:mm"); fontSize: 96; fontWeight: 200 }
}
}Check it with java -jar tools/owl.jar review . faces/<you>/<name>/face.owl. Its previews are
pictures of the whole page at a phone's size, which scripts/store-previews.sh makes too. A face that
uses theme colors gets previews/<theme>.webp like a widget, not only preview.png. Launchers from before faces (0.8.1 and older) only read
index.json and apps.json, so they never see one.
- One folder per widget, and only
widget.owl,preview.png,README.mdandpreviews/<theme>.webpin it (face.owlfor a face,app.owlfor an app). - You can only add or change widgets, faces and apps under your own username.
metaneeds adescription(10-200 characters), aversionand alicense. Add acategory(news,dev,productivity,time,world,sport,finance,media,games,pets,fun,homeorsystem) so it shows under that tab in the store; without one it goes under "other".- Every package the commands need goes in
requires. CI checks that the packages exist in Arch and warns about programs whose package isn't declared. meta { owl: N }is the language level the widget needs (none is level 1). It has to be one that owl.txt lists as supported; a level marked deprecated there is only allowed for widgets that aren't changed. A launcher older than a widget's level can't install or update it, so raiseowlonly when the widget uses something that needs it.- Updates raise the version. If an update changes the commands or packages, the app asks users to approve it again.
- Values go into commands as
${sh(value)}, outside any quotes, or as numbers (${int(n)}): anything else could run whatever a server or a file sends. CI rejects it. - No hidden or surprising behavior. Commands that pipe downloads into a shell or run
downloaded files, delete recursively, ask for root, decode base64 or use
evalare flagged, and need a good reason and a clear description. - No personal data: tokens, personal paths or a hard-coded location.
Widgets run shell commands inside the phone's Arch system, not with Android permissions. They can still read and change files there, and use the network. Reviewers read every command; the CI summary lists them all, with anything risky flagged.
widgets/<author>/<name>/widget.owl the widget
widgets/<author>/<name>/preview.png optional screenshot
widgets/<author>/<name>/previews/ optional screenshots per Omarchy theme (<theme>.webp)
faces/<author>/<name>/face.owl a face, with preview.png and previews/ like a widget's
apps/<author>/<name>/app.owl an app, with preview.png and previews/ like a widget's
order.txt the order of the store
docs/LANGUAGE.md the widget language
w/index.html where a shared widget's link lands: shows it, opens the launcher
owl.txt the owl levels the store takes, and the launcher that runs each
tools/owl.jar the checker CI runs (built from the latest launcher release's owl module)
runtimes/quickshell/ OWL for Quickshell on Linux: the same widgets, drawn
by Quickshell (Omarchy Mobile's widget board uses it)