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, or a PNG embedded as an asset. The launcher draws no
frame around it, so like the store's other apps it's a colored picture on a rounded tile of its own:
a 256×256 viewBox with a rx="56" rect first, one big subject in flat fills of a few colors, with
light and shadow, and no text. The launcher's docs/apps.md has the details. 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 256 256">
<rect width="256" height="256" rx="56" fill="#24283B"/>
<rect x="70" y="58" width="128" height="164" rx="14" fill="#16161E" fill-opacity="0.5"/>
<rect x="64" y="50" width="128" height="164" rx="14" fill="#F4E3A1"/>
<path d="M64 64a14 14 0 0 1 14-14h100a14 14 0 0 1 14 14v18H64z" fill="#E0AF68"/>
<path d="M86 112h84M86 140h84M86 168h52" stroke="#B8A36A" stroke-width="10" stroke-linecap="round"/>
<g transform="rotate(45 178 168)">
<rect x="164" y="88" width="28" height="104" rx="4" fill="#7AA2F7"/>
<rect x="164" y="88" width="10" height="104" fill="#A9C1FF"/>
<rect x="164" y="76" width="28" height="18" rx="4" fill="#F7768E"/>
<path d="M164 192h28l-14 26z" fill="#F0D2B0"/>
<path d="M173 209h10l-5 9z" fill="#1A1B26"/>
</g>
</svg>"""
state notes = [] persist
Column {
Input { placeholder: "write a note…"; clear: true; onSubmit: notes = [value] + notes }
for n in notes { Text { text: n } }
}
}An app is part of Omarchy, so its own panels, cards and buttons follow the user's style instead of a phone app's:
- No fixed rounded corners. Round a shape by the user's corner style,
radius: 8 * cornersfor a card and3 * cornersfor a chip, which is square on Omarchy (cornersis 0). Aradius: 16card looks out of place next to everything else. - No see-through black or white "glass" cards (
background: alpha(black, 0.4)with a rounded border) as the default panel. Use the theme's colors (surface,border,accent) for a tool, or the colors of the app's own art for a game.
A game draws its own world, so its menus, HUD and buttons are made to fit that world, not laid over it as a generic app sheet:
- Shapes from the art.
simonschubert/voxel-rallyis built of boxes, so its buttons and panels are square solid blocks on a darker 5 dp "ledge" (aSpacerunder them), and a pressed button sinks onto it. A pixel-art game gets hard pixel edges; a neon one thin glowing lines. - A font that fits, by URL from Google Fonts, like
simonschubert/sunset-heist's Anton or voxel-rally's Silkscreen (let PIX = "https://raw.githubusercontent.com/google/fonts/main/ofl/silkscreen/Silkscreen-Regular.ttf", thenfont: PIX, in Canvastext()too). Without one, a game shows the theme's terminal font. - Big controls a thumb finds without looking (a held button uses
onPressandonRelease), and words kept short.
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.
A face can have several pages, installed side by side: its others go beside face.owl as
page-2.owl, page-3.owl, ..., numbered without gaps, and land right of page 1 in that order. Each
is a face of its own (face "name" { }), but only face.owl's meta describes the face: a page needs
no description, version or license, just the owl level it uses. Every page is reviewed, the face's
commands and packages are those of all its pages, and it needs owl 14 or the highest level a page uses.
Adding, changing or removing a page needs face.owl's version to go up. A page's pictures go in
screens/<page>/<theme>.webp, which scripts/store-previews.sh draws in the same run as page 1.
Check them all with java -jar tools/owl.jar review . faces/<you>/<name>/*.owl.
- One folder per widget, and only
widget.owl,preview.png,README.mdandpreviews/<theme>.webpin it (face.owlfor a face, with itspage-2.owl, ... andscreens/<page>/<theme>.webpif it has several pages;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
faces/<author>/<name>/page-2.owl a face's second page, if it has more; its pictures in screens/2/
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)