Skip to content
DotfilesDotfiles
Esc
↑↓navigate↵open⌘Jpreview
On this page

Omarchy Shell

Omarchy Quickshell bar, panels, and timmo.* plugins.

The Omarchy Shell is the long-running Quickshell process (omarchy-shell) behind the bar, notifications, OSD, launcher, and settings on Omarchy. These dotfiles extend it with timmo.* plugins instead of forking Omarchy’s shell.

~/.config/omarchy/shell.json is generated, not hand-edited. dot merges Omarchy’s default layout with omarchy-plugins.json (and an optional private overlay). After plugin or layout changes, use omarchy restart shell when a hot-reload is not enough. dot omarchy shell config regenerates the layout without a full stow.

Layout

Public omarchy-plugins.json owns placement and per-host tweaks. Stock omarchy.weather and omarchy.agents are removed, and its disable list turns off stock plugins that another program replaces, optionally on some hosts only: the laptop turns off omarchy.notifications so Hokum owns notifications there (it draws black cards on the desktop’s NVIDIA GPU). timmo.workspaces and timmo.clock replace the stock workspace and clock widgets.

Several centre/right widgets are primary-output only, with host-specific outputs (desktop HDMI-A-2, laptop eDP-1). A private overlay can add or override plugins without publishing them.

Bar and panel plugins

Plugin Role
timmo.workspaces Dynamic workspace numbers (no persistent empties), with the focused workspace’s name and every name on bar hover; focused full opacity, others dimmed
timmo.upnext Twitch live channels, YouTube uploads and the watch-later queue from the local upnext daemon
timmo.git Managed-repo state, recent commits, GitHub notifications, release reviews, and open pull requests in one centre widget and panel, read from the dot daemon’s status file
timmo.command Interval command cell, or one following a runtime file; here shows Dotfiles and watched package update status from the dot daemon’s status file
timmo.stream-command Streaming status JSON for long-running watchers; available but not placed on the public bar
timmo.home-assistant Home Assistant status on the right
timmo.system-bridge Local System Bridge health (bar + detail panel)
sceny.devices Phones and tablets in the bar through KDE Connect
timmo.notes Notes vault browse/search/capture panel wired to the notes CLI
timmo.services Health and run history of registered user services (bar + panel), read from the dot daemon’s status file
timmo.clock Compact clock with calendar, year progress, and world clocks (replaces stock clock)
timmo.momentumctl Headset panel via momentumctl; panel-only in the public layout
timmo.plannotator-inbox Threads waiting on you in the local Plannotator Inbox (bar + panel); opens the Inbox as an Omarchy web app rather than redrawing it
timmo.upkeep What needs you in Upkeep from upkeep status --json (bar + panel); each row opens its dashboard page at the direct address

Sources

Custom plugins live under omarchy/.config/omarchy/plugins/. Some are local QML in this repo (workspaces, command, stream-command, git, services, plannotator-inbox, upkeep, workspace-context, workspace-relayout, popup-loading); others are managed plugins (clock, upnext, notes, system-bridge, momentumctl, sceny.devices) with placement recorded in omarchy-plugins.json. workspace-context shares attached Herdr workspace changes with the bar; workspace-relayout and popup-loading are overlays rather than bar cells.

Most managed plugins come from repositories dot already tracks and pulls. Their registry entry names the repository ("repository": "timmo001/omarchy-clock", plus path when the plugin sits in a subfolder such as omarchy-plugin), and dot stow exports that folder from the checkout’s remote default branch. Only pushed commits reach the bar, and a push needs no commit here. dot omarchy plugin update <id> fetches and redeploys one straight away.

Plugins without a tracked repository, such as sceny.devices, are submodules. Third-party bar plugins are imported that way too: Omarchy’s omarchy plugin add (backed by dot omarchy plugin) checks them out as submodules, and dot omarchy plugin add <id> <url> <checkout> --path <subfolder> takes a plugin from a subfolder. Either way, dot stow copies the files as real files, because Omarchy rejects plugin-directory symlinks. Placement and config live in omarchy-plugins.json, and a private overlay can extend that layout the same way. An onlyHosts list (for example ["desktop"]) keeps an entry out of the generated layout on other hosts.

Do not hand-edit the live shell.json. Change the generator or registry, rebuild dot when needed, then stow.

Last updated on