Zero-config React with built-in SSR, automated quality gates, and AI-ready project structure - ship clean code whether you write it yourself or with an AI assistant.
Written in Rust: a tiny background daemon drives the hardware, and a GTK4/libadwaita app lays out your keys.
Features
Six action types
Launch app: pick from your installed apps; the app's icon and name come along. Apps launch through uwsm-app, the same way Omarchy launches them.
Run script: optionally in a terminal so you can watch the output.
Play sound: through PipeWire (pw-play), with per-key volume.
Open website: one click fetches the site's icon for the key. The icon is requested from the site itself; DuckDuckGo's icon service is used only if the site offers none, and the app tells you when that happens.
Hyprland: any dispatcher. Lua (hl.dsp.focus({ workspace = "3" })) is passed straight to hyprctl dispatch. Classic syntax (workspace 3, movetoworkspace 2, togglefloating, fullscreen, killactive, exec …) is translated automatically on Hyprland versions that use a Lua config.
Open page: pages and folders, for more keys than your deck has. A new page starts with a Back key, so a key that opens it works like a folder.
Icons your way
PNG, JPEG, SVG, WebP or GIF images.
App icons from your icon theme.
Nerd Font glyphs, drawn in your theme's accent colour.
Labels are rendered in your Omarchy font.
Theme aware. Key backgrounds, labels, glyphs and the press highlight come from the active Omarchy theme. Run omarchy theme set … and the deck re-renders instantly.
Live editing. Changes land on the hardware as you type, and the deck shows whichever page you're editing. Drag keys to rearrange them. Press a physical key to jump to it in the editor.
Robust. Reconnects after unplug/replug, and a typo in a hand-edited config keeps the last good layout on the deck. Apps opened from the deck keep running when the daemon restarts or upgrades. Uses about 9 MB of RAM and 0% CPU at idle.
Undo and backups. A deleted page or cleared key can be undone, and the app keeps backups of your config.
Hold keys. A key can do one thing when pressed and another when let go: push-to-talk to your AI agent with voxtype.
On your Omarchy bar. An optional icon shows whether the deck is connected and which page it's on, and opens the app.
Portable. Everything lives in ~/.config/omadeck/, and imported icons are copied into it, so you can copy that folder to another machine.
Install
Prebuilt release (recommended, no Rust needed)
curl -LO https://github.com/thewizster/omadeck/releases/download/v0.3.0/omadeck-0.3.0-x86_64-linux.tar.gz
curl -LO https://github.com/thewizster/omadeck/releases/download/v0.3.0/SHA256SUMS
sha256sum -c SHA256SUMS
tar xzf omadeck-0.3.0-x86_64-linux.tar.gz && cd omadeck-0.3.0-x86_64-linux
scripts/install.sh
The installer uses the prebuilt binaries, enables the omadeckd user service and offers to set
up the udev rule (details below). If the deck isn't detected straight away, replug it once.
Coming soon:omarchy pkg add omadeck-bin from the Omarchy Package Repository. The package
is in review.
From source
# Rust toolchain, if you don't have one yet
mise use -g rust@latest
git clone https://github.com/thewizster/omadeck && cd omadeck
scripts/install.sh
The script:
builds a release binary (pinned to Cargo.lock), or uses the prebuilt ones from a release tarball, and installs omadeck + omadeckd to ~/.local/bin;
adds a launcher entry;
enables the omadeckd systemd user service, which starts with your graphical session;
if your user can't already open the deck, shows the udev rule and the exact sudo commands, and runs them only if you answer y.
To remove omadeck, run scripts/uninstall.sh. It also removes the Omarchy bar widget, and leaves your config in place.
Mute · Night light · Next wallpaper · a sound · Lock
Click any key to change it, or clear it with the trash button. The ▶ button tests the action without touching the deck.
Pages and folders
The switcher above the deck picks the page you're editing; + adds a page, and the pencil and trash buttons rename or delete it. To make a folder, set a key to Open page and click New page: you get a page with a Back key already in place, and the key gets a folder symbol. Open it with › to fill it.
On the deck, Go back returns to the page you came from, or Home. Renaming a page updates every key that opens it.
Hold keys (push-to-talk)
A key can also do something when you let go of it: set When released in the editor. With
voxtype (Omarchy's dictation), a key that runs
voxtype record start when pressed and voxtype record stop when released gives you
push-to-talk: hold it, speak to your AI agent, let go. If the deck is unplugged or the service
stops while you're holding a key, it's let go then, so nothing stays switched on.
Omarchy bar
On Omarchy, the app offers once to add an omadeck icon to the bar. It shows whether your deck
is connected and which page it's on, and opens omadeck when clicked. Turn it on or off any time
with Show in Omarchy bar in the app's settings (or omarchy plugin disable dev.omadeck).
Command line
omadeckd run the daemon (normally via systemd)
omadeckd list show connected decks
omadeckd press 3 [PAGE] run key 3's action, then its release action (keys count from 0)
omadeckd snapshot x.png [PAGE] render the layout to an image
omadeckd status [--follow] the deck's state as Waybar-style JSON (keeps printing with --follow)
omadeckd press is handy in Hyprland bindings and scripts, for example to share one action between a key and a keyboard shortcut.
Configuration
The config file is ~/.config/omadeck/config.toml. The app edits it for you, but it's plain TOML and safe to edit by hand, even while the app is open; the daemon and the app reload it as soon as you save. If the app can't read your edit, it shows the error and leaves the file alone until you fix it. See examples/config.toml.
Each time the app opens, and before it deletes a page, it keeps a copy of config.toml in ~/.local/state/omadeck/backups (the newest 20). Deleting a page or clearing a key can also be undone from the notice that pops up.
brightness = 70
[style]
follow_theme = true # colours from the active Omarchy theme
[[key]]
index = 0 # left-to-right, top-to-bottom, from 0
label = "Terminal"
icon = "icons/utilities-terminal.png" # relative to ~/.config/omadeck
[key.action]
type = "app"
command = "xdg-terminal-exec" # or a desktop id like "firefox.desktop"
[[key]]
index = 10
label = "Mute"
glyph = "\U000F075F" # Nerd Font symbol (or "f075f" / "U+F075F")
[key.action]
type = "app"
command = "omarchy audio output volume mute-toggle"
[[key]]
index = 4
label = "Media"
glyph = "\U000F024B"
[key.action]
type = "page" # open another page
page = "Media"
[[page]] # top-level [[key]]s are the Home page; more pages go here
name = "Media"
[[page.key]]
index = 0
label = "Back"
[page.key.action]
type = "back" # previous page, or Home
Action types:
type
Fields
app
command
script
path, terminal
sound
file, volume (0.0–1.5)
url
url
hyprland
dispatch
page
page (a page name)
back
A key's [key.on_release] (or [page.key.on_release]) takes any of these except page and
back, and runs when the key is let go.
Per-key look overrides are background, label_color and show_label.
How it works
crates/
omadeck-core/ config, Omarchy theme, key renderer, actions, IPC types
omadeckd/ daemon: owns the USB device, paints keys, runs actions
omadeck-gui/ GTK4 + libadwaita configurator (binary: omadeck)
packaging/ systemd unit, udev rule, desktop entry, AUR PKGBUILDs
scripts/ install / uninstall / package a release
site/ project website: static HTML/CSS/JS with an interactive demo
Single source of truth. The GUI only writes config.toml (atomically). The daemon watches it, plus Omarchy's theme state in ~/.local/state/omarchy/current, and repaints.
Same pixels everywhere. The renderer in omadeck-core is shared, so the previews in the app are rendered by the same code that paints the hardware.
Event feed. The daemon publishes connect/disconnect, page and key events as JSON lines on $XDG_RUNTIME_DIR/omadeck.sock. The app uses this for its status line, press-to-select and following the deck's page, and sends back the page you're editing so the deck can show it.
Troubleshooting
"Service not running": systemctl --user status omadeckd (press q to leave its pager, or add --no-pager). Logs: journalctl --user -u omadeckd -f.
Deck found but can't be opened (the app's title says "Can't open the Stream Deck"): replug the deck. If that doesn't help, install the udev rule (packaging/70-omadeck.rules → /etc/udev/rules.d/), then replug it again.
Only one program can own the deck. Quit the Elgato software or other tools such as streamdeck-ui first.
Release actions: keys that act on release too, for push-to-talk dictation (0.3.0)
Omarchy bar widget: deck status on the bar, one click to the app (0.3.0)
Templates: ready-made pages to add in one click, starting with Omarchy Basics (your AI agent, dictation and everyday Omarchy keys); save any page as a template and share it
Toggle keys with on/off faces (mute, night light, …) that reflect real state
Multi-actions: run several actions from one key, with optional delays
Stream Deck +: dials and touch strip (volume, brightness, scrubbing)
OBS scene and recording keys via obs-websocket
Live keys that show a clock, CPU usage or the active workspace
Multiple decks with a layout per serial number
How this was built
omadeck was built on Omarchy by Raymond Brady together with Claude Code (Anthropic's AI coding agent), as a showcase of what that pairing can do. Every change goes through the same checks as any contribution: rustfmt, clippy -D warnings, tests, CI and testing on real hardware.
