wikis / Omarchy / wiki / concepts / productivity-tools.md view as markdown report a mistake

Definition

Omarchy's productivity layer is a set of everyday utilities — unified clipboard/history, reminders, quick-glance notices, text extraction and dictation, screenshots/recording, and mode toggles for idle/screensaver behavior. Toggles specifically share one design pattern (a hotkey, a menu entry, and an equivalent omarchy toggle CLI command hitting the same switch); several of the other utilities also surface through the Omarchy shell's own freedesktop-compliant notification daemon for toasts, history, and bar indicators, but not every utility here goes through that daemon or exposes all three access surfaces.

How It Works

The shared pattern

Toggles in this layer follow one consistent shape: a hotkey does the thing, the same action is reachable from the Omarchy menu (Super + Space) under a Trigger category, and an omarchy toggle <thing> CLI equivalent exists for scripting. This is deliberate — it makes toggles fully automatable, not just clickable. Other utilities in this layer typically expose a hotkey and often a CLI form, but not all of them have a documented menu entry.

Unified clipboard & history

Linux conventionally splits copy/paste behavior between the terminal (Ctrl + Shift + C/V) and everything else (Ctrl + C/V), which is jarring for anyone not raised on it — doubly so coming from macOS's Cmd-centric habits. Omarchy unifies this with hotkeys that work almost everywhere:

(Most AI agent harnesses are an exception: they still use Ctrl + V for pasting images, while Super + V remains correct for text.) Clipboard history is provided by the Omarchy shell itself and covers both text and images: select an entry with Return and it becomes the active clipboard, ready for Super + V; typing while the history is open searches it live.

Reminders

Super + Ctrl + R sets a reminder (a countdown plus a message); Super + Ctrl + Alt + R lists all pending ones; Super + Ctrl + Shift + R clears all of them; the same three actions live under Trigger > Reminder. From the terminal: omarchy reminder 7 'Tea ready'.

Reminders are not their own daemon — they ride entirely on systemd and the notification system below. bin/omarchy-reminder <minutes> [message] creates a transient systemd user timer via systemd-run --user --collect --on-active=<minutes>m, named omarchy-reminder-<minutes>m-<epoch>. Because a systemd unit name can't carry arbitrary text, a custom message is stashed separately at $XDG_RUNTIME_DIR/omarchy-reminders/<unit>.message. --collect means a fired timer cleans itself up entirely — no leftover state. All reminder state therefore lives in systemd itself: show/clear work by enumerating systemctl --user list-timers "omarchy-reminder-*.timer" (show --json is what the bar's Reminder indicator polls, refreshed by the same omarchy-shell -q omarchy.indicators refresh call the timers themselves make on fire). omarchy-reminder -i opens a two-step minutes/message overlay that shells back out to the same omarchy-reminder command to actually set it.

Notices

Three hotkey "notices" give an instant glance at ambient state, each with its own hotkey:

Weather location is detected from IP address by default (usually close enough, not always exact). Pin it with omarchy weather location --set Malibu, be precise with coordinates via omarchy weather location --set Malibu 34.0259,-118.7798, check the current setting with omarchy weather location alone, or reset to auto-detection with --clear.

Text extraction & dictation

Super + Ctrl + PrtScr selects a screen region and runs it through the open-source Tesseract OCR model, placing the resulting text on the clipboard for an immediate Super + V paste — useful for pulling addresses out of images or phone numbers out of website headers.

Dictation is provided by Voxtype, installed via Install > AI > Dictation. It defaults to a 150MB base English model; voxtype setup model switches models, and `/.config/voxtype/config.tomlholds the rest of its settings. Once installed, holdingF9or toggling withSuper + Ctrl + X` dictates directly into whatever input is currently focused.

Screenshots & recording

Everything screen-capture related hangs off the Print Screen key (or Super + Ctrl + C for a menu equivalent on keyboards without one):

Screenshots: Print Screen freezes the screen, then a drag selects a freeform region while a single click snaps to whatever rectangle was clicked (a window, or the whole monitor if clicked on empty space/the bar); pressing Print Screen again dismisses the picker. The result lands both as a PNG in ~/Pictures (override with OMARCHY_SCREENSHOT_DIR) and on the clipboard, with a notification thumbnail that opens the shot in Tensaku, the annotation editor, for arrows/boxes before sharing (swap editors with OMARCHY_SCREENSHOT_EDITOR; click the notification or hit Super + Alt + , to reopen the last one). From the terminal, omarchy screenshot takes the same default shot, or be explicit: omarchy capture screenshot [region|windows|fullscreen] [copy|save]. While the selection picker is open, it's fully keyboard-drivable: Return captures the highlighted window, Ctrl + Return captures the whole screen, Tab/Ctrl + Tab cycle windows, and arrow keys move the highlight directionally.

Screen recording: Alt + Print Screen opens a soundtrack choice — no audio, desktop audio, desktop+mic, or desktop+mic+webcam (webcam option only appears if a camera is present) — then the same region/window/monitor picker as a screenshot. Recording runs on gpu-screen-recorder, GPU-encoded at 60fps with a CPU fallback, producing an MP4 in ~/Videos (override with OMARCHY_SCREENRECORD_DIR, which — unlike the screenshot directory — must already exist or recording refuses to start). A bar indicator shows while recording; click it, hit Alt + Print Screen again, or use the Stop Screenrecording menu entry to stop. On stop, the first frame is trimmed and, if there's audio, it's normalized to -14 LUFS with the PipeWire capture pop at the start muted — then a clickable thumbnail notification opens the result in mpv. When recording with a webcam, the camera appears as a pinned, cropped portrait overlay in the bottom-right corner, resizable on the fly between three proportional sizes (small/medium/large, medium default) with Super + Alt + [ / Super + Alt + ] — or directly via omarchy-capture-webcam-resize small|medium|large|reset. The overlay anchors to the recorded monitor or region's corner, whichever was captured.

Text, QR codes, and colours: Super + Ctrl + Print Screen OCRs a region to the clipboard (see above). Trigger > Capture > QR Code decodes a QR code from a selected region straight to the clipboard only — never printed, never shown in the notification, and marked sensitive so it's excluded from clipboard history. This matters because QR codes routinely carry secrets (e.g. the otpauth:// URI behind a 2FA setup), so nothing gets logged. Super + Print Screen (or Trigger > Capture > Color) is an eyedropper — click anything on screen to put its colour on the clipboard; press the hotkey again to cancel without picking.

Transcoding: Super + Ctrl + . (or Trigger > Transcode) offers a fuzzy picker over ~/Pictures and ~/Videos, then a target format and size. Images go to jpg/png at high/medium/low (capping width at 3160/2160/1080px); video goes to mp4 or animated gif at 4k/1080p/720p. The output is written alongside the original with the resolution in its name (e.g. demo-1080p.mp4) and its path copied to the clipboard as a file URI, ready to drag-and-drop elsewhere. From the terminal: omarchy transcode ~/Videos/demo.mov mp4 1080p; omarchy transcode ascii turns an image into ASCII art (mostly used for branding — see theming).

Super + Ctrl + S opens the Share menu (LocalSend — see tuis guis and browsers) to send a captured file to another device.

Toggles

Omarchy calls a temporary mode switch — night light for an hour, do-not-disturb while presenting, stay-awake while watching something — a toggle, and every one of them is reachable from the Omarchy menu and via omarchy toggle <thing>, though not every toggle has a dedicated hotkey (see the em-dash rows below). Super + Ctrl + O (or the Omarchy menu) opens Trigger > Toggle; running omarchy toggle alone lists the whole group.

Touchpad, touchscreen, and hybrid GPU toggles live under Trigger > Hardware (Super + Ctrl + H) instead, since they only appear when the relevant hardware exists; the touchpad/touchscreen states specifically survive a Hyprland reload because the disabled state is written to a small Lua file Hyprland sources on startup. Most toggle state is just a flag file under ~/.local/state/omarchy/toggles/, named for the off state (screensaver-off, suspend-off, bar-off), so their presence means the feature is disabled; omarchy-toggle-enabled <name> gives a script an exit code instead of parsing files directly.

Active modes surface as small glyphs in the bar's indicators widget (dictation, screen recording, pending reminders, night light, do-not-disturb, stay-awake) — inactive ones stay hidden until hovered (dimmed, clickable to enable), and setting alwaysShow: true on the omarchy.indicators entry in ~/.config/omarchy/shell.json (see omarchy cli and shell) keeps them all visible permanently.

Night light warms the display to 4000K (back to 6500K on toggle-off), driven by hyprsunset, which the toggle starts if not already running. ~/.config/hypr/hyprsunset.conf ships an identity profile so nothing changes until requested; replacing it with a time profile (profile { time = 20:00; temperature = 4000 }) and adding o.launch_on_start("hyprsunset") to ~/.config/hypr/autostart.lua makes it switch automatically by clock time. The 4000K/6500K toggle pair itself is fixed regardless.

Do not disturb (Super + Ctrl + ,) suppresses on-screen toasts (with a crossed-out bell indicator in the bar) but loses nothing — a silenced notification is still written to history, viewable with Super + Shift + Alt + ,. Two categories still get through even while silenced: Omarchy's own action-confirmation toasts ("Theme changed") and genuinely critical command-line alerts — chat apps that mark everything critical to force visibility don't qualify (see the sender contract below for exactly why).

Idle behavior belongs to the Omarchy shell, configured as a top-level idle block in ~/.config/omarchy/shell.json:

{
  "version": 1,
  "idle": { "screensaver": 150, "lock": 300 }
}

Both values are seconds counted independently from the moment idling began (not from each other) — with defaults, the screensaver appears after 2.5 minutes and the lock screen takes over at 5 minutes regardless of whether the screensaver ran. Dismissing the screensaver counts as activity and cancels a pending lock. Super + Ctrl + I (omarchy toggle idle) disables locking-on-idle entirely, shows a coffee-cup bar indicator, and toggling again restores normal behavior; omarchy toggle idle status prints the current state as JSON for scripts. This governs locking/screensaver only — suspend and hibernation are configured separately (see system management).

The screensaver is Omarchy's own ASCII-art display running random text effects, one instance per monitor, dismissed by any key or mouse movement. Super + Esc (System > Screensaver) forces it on demand regardless of the idle toggle state; omarchy toggle screensaver disables the idle-triggered version specifically. It needs a terminal it knows how to configure (Alacritty, Foot, Ghostty, or Kitty) and will say so if the default terminal isn't one of those. Its logo is customizable (upload a PNG/SVG, converted to ASCII) under Style > Screensaver — see theming.

The lock screen (Super + Ctrl + L) blanks the display via the Omarchy shell, resets the keyboard layout to the first configured one (so a password isn't typed in the wrong alphabet), and locks 1Password if it's running. It accepts a password or an enrolled fingerprint — see security for hardware authentication.

The notification substrate

All of the above — reminders, silenced-notice history, active-mode indicators — sits on one shared piece of infrastructure: the Omarchy shell is itself the freedesktop notification daemon. shell/plugins/notifications/Service.qml hosts a Quickshell NotificationServer that claims org.freedesktop.Notifications on the session bus directly — there is no dunst or mako running separately. Anything speaking the standard protocol (notify-send, libnotify apps, Chromium web apps) lands here and renders as a stacked toast card in the top-right corner.

A toast stays on screen for at least 5s (low urgency), 8s (normal), or indefinitely (critical), stretched up to 30s if the sender requested a longer expire_timeout; hovering pauses the countdown, and a content update (via replaces_id) restarts it. Every popup is mirrored to a JSON file under ~/.local/state/omarchy/notifications/, so live toasts survive the shell restart that omarchy-update performs; when a toast leaves the screen it moves into notifications/history/, trimmed to the newest ten (that history directory is what "show history" replays). Referenced images/avatars are copied into notifications/images/ because senders often delete their originals immediately.

Silencing (DND) is a single boolean, dnd, persisted in ~/.local/state/omarchy/notifications.json and toggled over shell IPC (toggleDnd/setDnd/dndState). Exactly two categories bypass it: app_name = omarchy-action (Omarchy's own just-did-something confirmations) and urgency: critical combined with app_name = notify-send (bare CLI emergency alerts) — critical urgency alone isn't sufficient, precisely because chat apps abuse it while setting their own brand as app_name, which fails the second half of the rule. A silenced notification anyone might want to check later is still written to history; genuinely ephemeral ones (the freedesktop transient hint, or app_name of notify-send/omarchy-action) are dropped entirely rather than archived.

The sender contract: the only way Omarchy code sends a notification is bin/omarchy-notification-send, which calls org.freedesktop.Notifications.Notify directly over the session bus via busctl --user — never raw notify-send. Because each value becomes one typed D-Bus parameter, there's no argv layer that could reinterpret a relayed piece of text (a video title, a filename) as an option or hint. Flags: -g/--glyph (Nerd Font icon glyph), --exec <program> [args…] (click command — consumes the rest of the line, must come last), --image, -i/--icon, --app-name (defaults to omarchy-action), -u/--urgency (defaults low), -t/--expire-time. Unknown flags are a hard error rather than passed through silently.

The click-command design is deliberately not a libnotify action (which would block the sender waiting for ActionInvoked and die unanswered across a shell restart). Instead the command is carried as a hint the shell executes itself, detached, from its own persisted copy — so a restored toast after a shell restart clicks exactly like a live one. --exec arguments are split by the caller's shell at the call site and passed as literal positional parameters (bash -lc 'exec "$@"'), never re-interpolated into a script string — so a value an attacker could influence (a downloaded video's title, a crashed process's name) can never be re-parsed as a command, closing off the class of bug that made the yt-dlp title RCE possible. A malformed argv hint fails closed rather than executing anything unvalidated.

Helper commands built on this contract: omarchy-notification-wait [timeout] (blocks until the shell has both answered IPC and claimed the bus name — used by anything sending near session start), omarchy-notification-dismiss <summary>, omarchy-notification-time/-battery (the one-line hotkey notices above), and omarchy-notification-weather (despite its name, not a sender — it toggles the weather panel directly). Subsystems built on the same contract include low-battery alerts, crash-capture notifications (see ai and dev tools), and pending-migration prompts.

Key Parameters

• idle.screensaver / idle.lock — seconds-since-idle thresholds in shell.json (defaults 150 / 300), counted independently.
• Toast durations — 5s low / 8s normal / indefinite critical, extendable to 30s via expire_timeout.
• History depth — newest 10 notifications retained per file-based history.
• OMARCHY_SCREENSHOT_DIR / OMARCHY_SCREENSHOT_EDITOR / OMARCHY_SCREENRECORD_DIR — capture output/tooling overrides (the recording directory must pre-exist; the screenshot directory does not).
• DND bypass rule — app_name = omarchy-action, or urgency: critical AND app_name = notify-send — both conditions required for the second case.
• Toggle flag files — under ~/.local/state/omarchy/toggles/, named for the off state.

When To Use

• Use omarchy toggle <thing> and omarchy-toggle-enabled <name> when scripting mode changes rather than hunting for flag files directly.
• Use the QR/color/text capture tools instead of a phone camera or a manual color-picker app — QR results are deliberately kept out of clipboard history for anything security-sensitive.
• Use the stay-awake toggle (Super + Ctrl + I / omarchy toggle idle) before long builds, presentations, or unattended recordings.
• Build custom notification senders through omarchy-notification-send rather than raw notify-send, to inherit DND rules and click-command safety automatically.

Risks & Pitfalls

• OMARCHY_SCREENRECORD_DIR must already exist — unlike the screenshot directory (which Omarchy creates automatically), recording refuses to start into a missing path.
• QR code capture is clipboard-only and excluded from history by design — don't expect to find a scanned QR value later; it's meant to be used immediately, precisely because QR codes often carry secrets like otpauth:// URIs.
• Critical urgency alone does not bypass DND — a chat app setting critical urgency with its own app_name is filtered exactly to stop that pattern; only notify-send-sourced critical alerts and Omarchy's own action toasts get through.
• --exec refuses a single quoted-string argument on purpose — passing a command as one pre-joined string (rather than separate shell-split arguments) would hand argument-boundary control to whatever data ends up in that string, which is the injection class the design explicitly closes.
• The screensaver requires a terminal it knows how to configure (Alacritty, Foot, Ghostty, Kitty) to toggle off the idle-triggered version — a different default terminal will surface an explicit error rather than silently failing.

Related Concepts

• omarchy cli and shell — shell.json's idle block and omarchy.indicators widget configuration
• tuis guis and browsers — LocalSend as the destination for Super + Ctrl + S sharing, and Tensaku's role after a screenshot
• theming — screensaver branding/logo and Aether-generated color extraction
• ai and dev tools — crash-capture notifications built on the same sender contract
• security — lock-screen authentication and clipboard-history exclusion for sensitive captures
• system management — suspend/hibernation as the power-management counterpart to idle locking

Sources

• raw/github_doc-manual-08-unified-clipboard-history-md.md
• raw/github_doc-manual-09-reminders-md.md
• raw/github_doc-manual-10-notices-md.md
• raw/github_doc-manual-11-text-extraction-dictation-md.md
• raw/github_doc-manual-12-screenshots-recording-md.md
• raw/github_doc-manual-13-toggles-idle-screensaver-md.md
• raw/github_doc-docs-notifications-md.md
• raw/github_doc-manual-22-guis-md.md
• raw/github_release-v4-0-0.md