The Top Bar¶

The strip along the top of your screen is the OmarOS bar. It's not a bolted-on status bar but part of the OmarOS shell, the single long-running Quickshell process that also draws the menu, the notifications, the OSD popups, and the lock screen. That's why it themes perfectly with everything else and why a panel opens instantly instead of spawning a new app.

It's also the one piece of the desktop that's always on screen, so it's worth knowing what all those little glyphs do.

What's on it by default¶

The bar has three sections. On the left sits the OmarOS logo (the menu launcher) and the workspace indicators. In the center you get the status indicators, the clock, Elsewhen (a world clock), the weather, and an OmarOS update badge. On the right: the system tray, the keyboard layout (when more than one is configured), bluetooth, network, audio, display, and power.

A few of those only show up when they have something to say. The keyboard layout appears only if you've configured more than one layout. The update badge appears only when there's an OmarOS update waiting.

Clicking around¶

Nearly every widget does something on left, right, and middle click, and several respond to scrolling. This is the part people miss — the right and middle buttons are where a lot of the good stuff hides.

Widget	Left	Right	Middle / scroll
Menu	OmarOS menu	New terminal	—
Workspaces	Focus that workspace on this monitor	—	Scroll: next/previous workspace
Clock	Calendar popup	Cycle the label format	Middle: timezone picker
Weather	Forecast popup	Full weather as a notification	Middle: refresh
Audio	Audio panel	Mute	Middle: panel · scroll: volume
Microphone	Mute the mic	—	Middle: audio panel · scroll: input volume
Network	Network panel	—	—
Bluetooth	Bluetooth panel	Toggle the radio	—
Display	Display panel	—	Scroll: brightness
Power	Power panel	Toggle the battery percentage	—
Media	Play/pause	Cover-art popup	Middle: next · scroll: prev/next
Tray	Hover to reveal the drawer	Right on the chevron to manage	—
OmarOS update	Run the update	—	—

Not everything in that table is on your bar out of the box. The media widget (MPRIS now-playing, with a scrolling track and artist) and the microphone widget are both built in but off by default — add them if you want them, as described below.

The panels¶

Clicking a bar icon opens a panel, which is a proper popup with sliders, lists, and keyboard navigation rather than a tooltip. Each one also has a hotkey, so you never have to aim at a 16-pixel glyph:

Hotkey	Panel
`Super + Ctrl + A`	Audio
`Super + Ctrl + W`	Network
`Super + Ctrl + B`	Bluetooth
`Super + Ctrl + D`	Display
`Super + Ctrl + P`	Power
`Super + Ctrl + Alt + D`	Calendar
`Super + Ctrl + Alt + E`	World clock
`Super + Ctrl + 1-9`	Toggle the nth panel in the right section

The panels aren't read-outs. They're where you actually do the thing:

Audio has a master volume slider, an output-device picker, and a per-app mixer, so you can turn down that one browser tab without touching everything else.
Network scans for Wi-Fi, shows signal strength, connects, and lets you pick a DNS provider.
Bluetooth lists your devices with connect/disconnect and battery levels.
Power shows battery stats, switches power profiles (it remembers a separate choice for battery and AC), and prints some system info.
Display carries a brightness slider, text size, monitor scaling presets, and — when you have more than one screen — per-monitor controls. See monitors for the deeper story.
Clock opens a month grid with ISO week numbers and month stepping.

Every panel takes the keyboard as well as the mouse: arrows move, Return activates, Tab steps to the neighbouring panel, and Escape closes.

Super + Ctrl + 1-9 counts panels left to right in the right section, skipping the tray since it has no panel of its own. So the number matches the icon you'd point at.

Indicators¶

The little cluster in the center is the indicators widget. These are status glyphs for modes you've turned on: do not disturb, night light, a queued reminder, an active screen recording, stay awake, and dictation. They light up when the mode is active and otherwise stay out of the way — hover anywhere on the bar to peek at the inactive ones. Clicking an indicator toggles that mode. One more is status only: a remote session lights up red while someone is connected to this machine through gliff.

If you'd rather they were always visible, set alwaysShow to true on the widget. And if you only care about some of them, list the ones you want in items: ["Dnd", "Reminder", "NightLight"]. You can have more than one indicators widget, so different sections can show different subsets.

Rearranging the bar¶

The bar configures itself. You don't have to open a config file to move things.

Grab an empty patch of the bar around the center and drag it toward another screen edge, and the bar moves there — left, right, top, or bottom all work, and every widget adapts (vertical bars fall back to compact icon-only forms). A click-and-hold starts the same drag. Double-left-click that same empty space to cycle the bar background from clear to glassy to opaque. And drag any widget to reorder it or throw it into another section; the other widgets slide apart to make room where it will land.

The middle of the bar is a box: whatever is in it stays centered as one group, and the widgets either side of it hang off its edges. While you drag a widget the box shows as an outline, or a line across the bar when it's empty, and you can drop into it or beside it. When a drop would land in the box, the box grows to take the widget in.

A widget you want around but not always in view can go in the tray's drawer: drag it onto the tray, and the drawer opens to take it. It sits there after the app icons, shows up whenever the drawer does, and keeps its drawer open while its panel is up. Drag it back out onto the bar to put it back.

If you'd rather pick from a menu, Trigger → Appearance → Menu Bar has the position, and Bar Background picks how the bar is drawn: Opaque Bar, Glassy Bar (see-through, with what's behind it blurred), or Clear Bar.

The same things have commands, which is what you want for a dotfiles setup:

omaros bar position bottom
omaros bar background glassy  # opaque, glassy, none, or cycle
omaros bar move omaros.weather --section centerBegin --index 0
omaros bar move omaros.bluetooth --section tray  # into the tray's drawer
omaros bar set omaros.clock format "HH:mm"
omaros bar defaults          # back to the shipped layout

To add or remove a widget entirely, use the plugin commands. omaros plugin list prints every widget the shell knows about with its id, and then:

omaros plugin enable omaros.media --section centerEnd
omaros plugin disable omaros.weather

Hiding the bar¶

Super + Shift + Space toggles the bar off and back on without killing the shell — panels and hotkeys keep working, you just get the pixels back. It's also in the menu under Trigger → Appearance → Menu Bar → Hide Bar.

The config file¶

All of it is stored in ~/.config/omaros/shell.json, under the bar key. Here's a trimmed version:

{
  "version": 1,
  "bar": {
    "position": "top",
    "background": "opaque",
    "layout": {
      "left": [{ "id": "omaros.menu" }, { "id": "omaros.workspaces" }],
      "centerBegin": [{ "id": "omaros.indicators" }],
      "center": [{ "id": "omaros.clock", "format": "HH:mm" }],
      "centerEnd": [{ "id": "omaros.weather" }],
      "right": [{ "id": "omaros.audio" }, { "id": "omaros.power" }]
    }
  }
}

Every widget is one entry in one of the five layout arrays, and its settings sit inline on that entry — there's no separate settings file and no config sub-object. The clock's format, formatAlt (what right-click cycles to), and verticalFormat all live right there on { "id": "omaros.clock" }.

center is the box in the middle of the bar: everything in it is centered on the screen as one group. centerBegin and centerEnd hang off either side of the box, which is how the clock stays dead center even as the weather and update badge come and go. Put more than one widget in center and they're centered together; leave it empty and centerBegin and centerEnd meet in the middle of the bar.

One rule worth internalizing: once you have your own shell.json, it's canonical. Until you customize anything, the shell reads OmarOS's default file. The moment you drag a widget, run omaros bar, or edit the file yourself, you own it — there's no deep merge, so new default widgets in future OmarOS releases won't appear on your bar automatically. omaros bar defaults puts the shipped layout back whenever you want a clean slate.

The same file also holds your idle timings at the top level, outside the bar key: idle.screensaver and idle.lock, both in seconds since you went idle. So the default screensaver kicks in at 150 seconds and the lock at 300.