# OmniWM OmniWM is a free, open-source, Developer ID-signed and Apple-notarized tiling window manager for Apple Silicon Macs running macOS 26 or later. It combines Niri-style orientation-aware scrolling containers and Hyprland-style Dwindle BSP layouts, selectable per workspace, with multi-monitor routing and optional local CLI/IPC automation. **[Website](https://omniwm.app)** · **[Documentation](https://omniwm.app/guides/quick-start/)** · **[Install](https://omniwm.app/guides/install/)** · **[Compatibility](https://omniwm.app/help/known-limitations/)**

## Demo Video [![Watch the demo](https://img.youtube.com/vi/WcHjGkuD2Fc/maxresdefault.jpg)](https://youtu.be/WcHjGkuD2Fc) ## Contributors

Thank you to everyone who contributed to OmniWM. Your ideas and code made a real difference.

--- ### 🏢 By Employer

Bitkey
_{━━━━━━━━}

Naoki Ikeguchi
_@siketyan

BlueLabs
_{━━━━━━━━}

Cristian Álvarez Belaustegui
_@crbelaus

EPAM
_{━━━━━━━━}

Aleksei Gurianov
_@Guria

Finanzguru
_{━━━━━━━━}

Janek Thomaschewski
_{@jthomaschewski}

GitHub
_{━━━━━━━━}

Ryan Hecht
_@RyanHecht

Google
_{━━━━━━━━}

muhammadkh
_@MuhammadKh

Luxor Labs
_{━━━━━━━━}

Albert Ilagan
_{@albertilagan}

Nx
_{━━━━━━━━}

Steven Nance
_@llwt

ReactSquad
_{━━━━━━━━}

Jan Hesters
_@janhesters

Spotify
_{━━━━━━━━}

Alexander Dergachev
_@Cy6erBr4in

SSW Consulting
_{━━━━━━━━}

Matt Wicks
_@wicksipedia

vhf
_{━━━━━━━━}

Lukas Gerlinski
_@lgerlinski

Viber
_{━━━━━━━━}

Yuri Chukhlib
_@YuriNachos

### 🎓 By Education

Assumption University of Thailand
_{━━━━━━━━}

Panuphong Burakitphachai
_@t1dotdev

Linnaeus University
_{━━━━━━━━}

Balazs Hevesi
_{@balazshevesi}

NTU Singapore
_{━━━━━━━━}

Nawat Suangburanakul
_@holmns

Olin College of Engineering
_{━━━━━━━━}

Cypress Frankenfeld
_@cypressf

SUSTech
_{━━━━━━━━}

Yang-Yiming
_@Yang-Yiming

### ✨ All Contributors

## Highlights - Ghostty-powered quake/sticky terminal - Native macOS window-tab support - Local IPC and `omniwmctl` automation - Scratchpads and sticky windows for any app - Overview - Unified command palette for windows and app menus - Menu Anywhere - Niri-style tabbed containers and Dwindle tile groups - Niri-style scrolling and Hyprland-style Dwindle BSP layouts - Status-bar icon concealment (similar to Ice) - Keep Awake (similar to Caffeine) - Interactive workspace and app-icon bar - Many more features not shown in the video. ## Compatibility and Limitations OmniWM requires Apple Silicon, macOS 26 or later, Accessibility, Input Monitoring, and `Displays have separate Spaces`. Screen Recording is optional. Read the complete [Compatibility, Requirements & Limitations](https://omniwm.app/help/known-limitations/) page before installing. - **Dwindle restore scope** — After a restart OmniWM rebuilds each Dwindle workspace from the persisted placements: split orientation and ratio, tab-group membership, tab order, and the active tab. Fullscreen state and the selected window are not restored, and once a window without a persisted placement is present, later windows insert normally instead of being placed from the catalog. - **Scratchpad membership** — Window membership lasts for the current OmniWM process. Scratchpad labels persist, but memberships do not. ## Performance & Trust OmniWM is built for high responsiveness and smooth, crisp animations. - **Direct macOS integration** — OmniWM uses public frameworks and selected Apple private APIs for window management and visual surfaces. - **Refresh-rate-aware animations** — Animation pacing follows the active display refresh rate, including 60, 120, and 144 Hz displays. - **SIP stays enabled** — Official OmniWM releases do not require disabling System Integrity Protection. - **Signed and notarized releases** — Official release builds are Developer ID signed and Apple-notarized. - **Free and open source** — OmniWM has no subscriptions, feature paywalls, trial limits, or usage caps and is licensed GPL-2.0-only. ## Requirements - macOS 26+ (Tahoe) on Apple Silicon - Hidden Bar concealment and optional issue-report rewriting require macOS 27 or later; rewriting also requires enabled Apple Intelligence and an available local model - Accessibility and Input Monitoring permissions (required at launch) - Screen Recording permission for Overview thumbnails, drag previews, and captured Hidden Bar glyphs (optional) - Displays have separate spaces **ON** (the macOS default; OmniWM pauses window management until it is enabled) ## Installation ### Homebrew OmniWM is in the official Homebrew cask repository: ```bash brew install --cask omniwm ``` This installs `OmniWM.app` and puts `omniwmctl` on your `PATH`. #### Upgrading Quit OmniWM first, then run `brew upgrade omniwm` and relaunch it. Homebrew replaces the app bundle underneath a running OmniWM. #### Migrating from the project tap `BarutSRB/tap` is retired: 0.6.7 was its final release, and every later version ships only through the official cask. If you installed from the tap, quit OmniWM and run these commands in this order: ```bash brew update brew upgrade omniwm brew untap BarutSRB/tap ``` `brew update` has to come first: it fetches the retired tap's redirect to the official cask and moves your install over. Untapping before that would offer to uninstall OmniWM. `brew reinstall --cask homebrew/cask/omniwm` is optional and only switches the install record to the official cask right away. ### Nix OmniWM is packaged in [nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/om/omniwm/package.nix), maintained by mmfallacy and samiser, and Home Manager ships an official [`programs.omniwm` module](https://github.com/nix-community/home-manager/blob/master/modules/programs/omniwm.nix), maintained by DavSanchez. The package installs the signed release artifact with `bsdtar`, so the Developer ID signature stays valid, and exposes `OmniWM` and `omniwmctl` on `PATH`. Both currently live on unstable branches only (the nixpkgs unstable channels and Home Manager `master`) and may trail the latest GitHub release. Install the package directly: ```bash nix profile install nixpkgs#omniwm ``` With nix-darwin or Home Manager, add `pkgs.omniwm` to `environment.systemPackages` or `home.packages`. For a declarative setup, enable the Home Manager module. It installs the package, runs OmniWM as a launchd agent, and writes `~/.config/omniwm/settings.toml` from an attribute set or a tracked TOML file: ```nix programs.omniwm = { enable = true; settings = ./omniwm-settings.toml; }; ``` Treat the declared TOML file or attribute set as authoritative: edit it and run Home Manager switch to apply changes. OmniWM preserves settings symlinks, so settings backed by a read-only Nix-store file cannot be saved from the GUI. Set `programs.omniwm.launchd.enable = false` if you prefer to start and quit OmniWM manually instead of having Home Manager manage its launchd agent. After either installation, complete the macOS setup in steps 3-7 below. ### GitHub Releases 1. Download the latest `OmniWM-v.zip` app archive from [Releases](https://github.com/OmniNull/OmniWM/releases) 2. Extract and move `OmniWM.app` to `/Applications` 3. In System Settings > Desktop & Dock > Mission Control, turn **ON** `Displays have separate Spaces` 4. Log out of macOS and log back in for that change to take effect unless you had it on already 5. Launch OmniWM and grant Accessibility and Input Monitoring when prompted 6. Optionally grant Screen Recording for capture-derived visuals 7. Return to OmniWM’s permissions window and click **Start OmniWM** or **Continue Without Screen Recording**. If a required permission still appears missing, click **Check Again** ## Updates OmniWM checks for updates by default. - On launch, OmniWM polls the latest GitHub release at most once per day. - Updates stay manual. OmniWM does not auto-download or auto-install a new release. - When a newer release is available, OmniWM shows a centered popup with release notes and actions for `Open Release Page`, `Copy brew upgrade omniwm`, `Skip This Version`, and `Not Now`. - You can control this from `Settings > General > Updates` or trigger a manual check from the status bar menu with `Check for Updates...`. ## Documentation The canonical documentation hub lives at [omniwm.app](https://omniwm.app). This README and the guides follow current `main`; features newer than the latest release are marked **Unreleased**. - [Documentation Home](https://omniwm.app/guides/quick-start/) - [Layout Modes](https://omniwm.app/guides/layouts/) - [Keyboard Shortcuts](https://omniwm.app/guides/keyboard-shortcuts/) - [Architecture Guide](https://omniwm.app/developers/architecture/) - [IPC & CLI Reference](https://omniwm.app/reference/cli/overview/) - [Contribution Docs](https://omniwm.app/developers/contributing/) - [Canonical Contributing Guide](CONTRIBUTING.md) ## IPC and CLI OmniWM ships with a bundled CLI, `omniwmctl`, for automation and scripting. IPC is disabled by default. Enable `Enable IPC` from the menu bar before using the CLI or any automation. Diagnostics can be scripted with `omniwmctl capture start trace`, `omniwmctl capture start performance`, `omniwmctl capture stop`, and `omniwmctl capture status`. For setup, installation options, commands, queries, rules, subscriptions, and security details, see the [IPC & CLI Reference](https://omniwm.app/reference/cli/overview/). ## Quick Start 1. Launch OmniWM from your Applications folder 2. In System Settings > Desktop & Dock > Mission Control, turn **ON** `Displays have separate Spaces` 3. Log out of macOS and log back in for that change to take effect unless you had it on already 4. Grant Accessibility and Input Monitoring in the launch permissions window, and optionally Screen Recording. Return to that window and click **Start OmniWM** or **Continue Without Screen Recording**; use **Check Again** if a required permission still appears missing 5. Windows will automatically tile in orientation-aware Niri containers: monitors using horizontal orientation show columns that scroll left and right, while vertical orientation shows rows that scroll up and down 6. Keep one macOS Space per display and navigate with OmniWM workspaces; extra native Spaces are tolerated (their windows are left to macOS, not tiled) 7. Use the defaults in [Keyboard Shortcuts](#keyboard-shortcuts) to navigate, and customize them in `Settings > Hotkeys` 8. Click the menu bar icon to access Settings, including `Settings > General > Updates` 9. Enable `Start at Login` under `Settings > General > Startup` to launch OmniWM automatically when you log in 10. Use `Check for Updates...` from the status bar menu whenever you want to run a manual update check 11. On macOS 27+, if you enable Hidden Bar and selected menu-bar icons disappear, right-click or Option-click OmniWM's menu-bar icon to open the Hidden Icons Bar and click any icon to use it. ## User Guide ### Multi-Monitor Setup OmniWM uses two display maps for different jobs: 1. Open **System Settings > Displays > Arrange**. Put the physically largest or widest display at the bottom. Place the next smaller display above and to its right so its bottom-left corner touches the lower display's top-right corner. Continue the same staircase for every additional display. This macOS map is a technical arrangement used for actual window placement; it does not need to look like your desk. 2. Open **OmniWM Settings > Monitors** and arrange the OmniWM routing map to match where the displays really sit on your desk. Tiles can be separated by empty grid cells, but every display must remain connected through a chain of shared rows or columns. A diagonal-only tile is disconnected and cannot exchange directional focus, window moves, or mouse warp. 3. Assign at least one workspace to every connected display. Window moves between displays need a destination workspace, so the setup assistant will not finish while a display is uncovered. You can reassign an existing workspace or explicitly add one for that display. 4. Leave **Mouse Warp** turned on for the recommended experience. It lets the pointer cross between displays according to the real-desk OmniWM map even though macOS uses the staircase. The setup assistant opens automatically when OmniWM first sees multiple displays. To review or redo it later, choose **Run Monitor Setup…** in **Settings > Monitors**. The assistant's **Show Numbers on Screens** action helps match each physical display to its tile. Routing, workspace-home, and Mouse Warp changes remain drafts until you finish the assistant. Custom arrangements are remembered for each set of connected displays, so home and work can keep different positions for the same laptop display. Reconnecting a saved set restores its arrangement automatically. If there is no exact match, OmniWM inherits the smallest saved arrangement containing every connected display; an uncovered set or an invalid grid follows macOS. Editing, resetting, or finishing setup saves only the connected set, leaving any larger arrangement unchanged. Simply connecting displays or opening Settings does not save an arrangement. Workspace assignments and other per-monitor settings remain separate. **Move Window Across Monitor at Edge** sends a window beyond a workspace edge to the adjacent routed display and always follows it. Dedicated monitor-move actions work independently of this setting and use **Follow Window to Monitor**, which also controls focus after ordinary window or column transfers to another workspace. Workspace homes can be **Main**, **Secondary**, **Tertiary**, or a specific display. By default Main is the display with the macOS menu bar and Secondary and Tertiary are the next displays in arrangement order. The **Monitor Roles** list in **Settings > Monitors** lets you rank displays instead: the highest-ranked connected display is Main, then Secondary, then Tertiary, and disconnected entries are skipped, so two external displays can hold fixed roles at your desk while the built-in display takes over when you unplug. The Quake terminal's **Main Monitor** option follows the same ranking. ### Layout Modes OmniWM offers two layout engines that you can switch between per workspace: **Niri (Orientation-Aware Scrolling Containers)** - On monitors using horizontal orientation, windows form vertical columns that scroll left and right; in vertical orientation, they form horizontal rows that scroll up and down. Each container can hold multiple windows or be "tabbed" (multiple windows, one visible at a time). **Hyprland Dwindle (BSP)** - Binary space partition layout that recursively divides screen space. Each new window splits the space in half, and a tile can group multiple windows as tabs. Best for traditional tiling with predictable layouts. Use the `Toggle Workspace Layout` shortcut below to switch layouts per workspace or configure them in GUI settings. ### Keyboard Shortcuts All shortcuts are customizable in Settings > Hotkeys. `Hyper` is the literal `Control + Option + Shift + Command` chord by default; which modifiers make up `Hyper` is configurable in Settings > Hotkeys (for example, exclude `Shift` to keep `Hyper + Shift + …` free for extra bindings). Changing the combination retargets every shortcut that currently resolves to `Hyper` onto the new one, so the shortcut list updates in place as you toggle the modifiers. Optionally pick a **System Hyper Trigger** — a single key (Caps Lock, F13–F20, or a left- or right-side modifier) or an extra mouse button that acts as `Hyper` while held (this needs Input Monitoring permission). Leave the trigger as `None` if you already produce `Hyper` another way, such as a Karabiner Elements remap. The tables below list all the default hotkeys: Layout legend: - `Shared` works in any active layout. - `Niri` works only when the active workspace uses the Niri layout. - `Dwindle` works only when the active workspace uses the Dwindle layout. Settings hides advanced actions from the shortcut list by default. Turn on `Include Advanced Commands` in Settings > Hotkeys to see and bind them; the tables below include both standard and advanced actions. #### Workspace | Action | Default Shortcut | Layout | |--------|------------------|--------| | Switch to Workspace 1-9 | `Option + 1-9` | `Shared` | | Move to Workspace 1-9 | `Option + Shift + 1-9` | `Shared` | | Switch to Workspace Slot 1-9 (position on the current monitor) | `Unassigned` | `Shared` | | Move to Workspace Slot 1-9 (position on the current monitor) | `Unassigned` | `Shared` | | Switch to Last Active Workspace (Back and Forth) | `Control + Option + Tab` | `Shared` | | Switch to Next Workspace | `Unassigned` | `Shared` | | Switch to Previous Workspace (Sequential) | `Unassigned` | `Shared` | | Move Window to Workspace Up | `Control + Option + Shift + Up Arrow` | `Shared` | | Move Window to Workspace Down | `Control + Option + Shift + Down Arrow` | `Shared` | | Move Column to Workspace 1-9 | `Unassigned` | `Niri` | | Move Column to Workspace Up | `Control + Option + Shift + Page Up` | `Niri` | | Move Column to Workspace Down | `Control + Option + Shift + Page Down` | `Niri` | #### Focus | Action | Default Shortcut | Layout | |--------|------------------|--------| | Focus Left / Right / Up / Down | `Option + Arrow Keys` | `Shared` | | Focus Down or Top / Up or Bottom | `Unassigned` | `Shared` | | Focus Top Window / Bottom Window | `Unassigned` | `Niri` | | Focus Window or Workspace Down / Up | `Unassigned` | `Niri` | | Focus Previous Window | `Option + Tab` | `Shared` | | Traverse Backward | `Unassigned` | `Niri` | | Traverse Forward | `Unassigned` | `Niri` | | Focus First Column | `Option + Home` | `Niri` | | Focus Last Column | `Option + End` | `Niri` | | Focus Column 1-9 | `Control + Option + 1-9` | `Niri` | | Focus Window 1-9 in Column | `Unassigned` | `Niri` | | Toggle Command Palette | `Control + Option + Space` | `Shared` | | Open Menu Anywhere | `Control + Option + M` | `Shared` | | Close Focused Window | `Unassigned` | `Shared` | | Toggle Workspace Bar | `Unassigned` | `Shared` | | Toggle Hidden Icons Bar | `Unassigned` | `Shared` | | Toggle Quake Terminal | `` Option + ` `` | `Shared` | | Toggle Overview | `Option + Shift + O` | `Shared` | | Toggle System Stats | `Unassigned` | `Shared` | #### Move Window | Action | Default Shortcut | Layout | |--------|------------------|--------| | Move Left / Right / Up / Down | `Option + Shift + Arrow Keys` | `Shared` | | Reorder Window Up / Down | `Unassigned` | `Shared` | | Move Window Down or to Workspace Down / Up or to Workspace Up | `Unassigned` | `Niri` | | Consume Window into Column / Expel Window from Column | `Unassigned` | `Niri` | #### Monitor | Action | Default Shortcut | Layout | |--------|------------------|--------| | Focus Next Monitor | `Control + Command + Tab` | `Shared` | | Focus Previous Monitor | `Unassigned` | `Shared` | | Focus Last Monitor | `` Control + Command + ` `` | `Shared` | | Move Workspace to Left / Right / Up / Down Monitor | `Unassigned` | `Shared` | | Move Window to Left / Right / Up / Down Monitor | `Unassigned` | `Shared` | The workspace-to-monitor actions target the active workspace and intentionally use the same temporary runtime override as `omniwmctl workspace move-to-monitor --force`. They do not rewrite the workspace's Home Monitor or swap workspaces, and unsafe fullscreen, hidden-app, scratchpad, or focus states still block the move. The window-to-monitor actions send the focused window directly to the current workspace on the adjacent routed display, independently of **Move Window Across Monitor at Edge**. The destination display must have at least one assigned workspace, which the Monitor Setup assistant verifies. They do not wrap when no monitor exists in that direction. **Follow Window to Monitor** controls whether focus follows the window; when it is off, you remain in the source workspace. #### Layout | Action | Default Shortcut | Layout | |--------|------------------|--------| | Toggle Fullscreen | `Option + Return` | `Shared` | | Toggle Native Fullscreen | `Unassigned` | `Shared` | | Balance Sizes | `Option + Shift + B` | `Shared` | | Cycle Size Forward | `Option + .` | `Shared` | | Cycle Size Backward | `Option + ,` | `Shared` | | Move to Root | `Unassigned` | `Dwindle` | | Toggle Split | `Unassigned` | `Dwindle` | | Swap Split | `Unassigned` | `Dwindle` | | Grow Horizontally / Vertically | `Unassigned` | `Dwindle` | | Shrink Horizontally / Vertically | `Unassigned` | `Dwindle` | | Grow / Shrink Focused Window | `Unassigned` | `Dwindle` | | Preselect Left / Right / Up / Down | `Unassigned` | `Dwindle` | | Clear Preselection | `Unassigned` | `Dwindle` | | Raise All Floating Windows | `Option + Shift + R` | `Shared` | | Rescue Off-Screen Floating Windows | `Unassigned` | `Shared` | | Toggle Focused Window Floating | `Unassigned` | `Shared` | | Assign Focused Window to Scratchpad 1-10 | `Unassigned` | `Shared` | | Toggle Scratchpad 1-10 | `Unassigned` | `Shared` | | Toggle Workspace Layout | `Option + Shift + L` | `Shared` | #### Container and Column | Action | Default Shortcut | Layout | |--------|------------------|--------| | Move Container Left / Right | `Control + Option + Shift + Left / Right Arrow` | `Shared` | | Move Container Up / Down | `Unassigned` | `Dwindle` | | Toggle Column Tabbed | `Option + T` | `Niri` | | Toggle Container Full Primary Span | `Option + Shift + F` | `Niri` | | Expand Container to Available Primary Span | `Control + Option + F` | `Niri` | | Move Column to First / Last | `Control + Option + Home / End` | `Niri` | | Move Column to Index 1-9 | `Unassigned` | `Niri` | | Set Container Primary Span -10% / +10% | `Option + -` / `Option + =` | `Niri` | | Set Window Secondary Span -10% / +10% | `Option + Shift + -` / `Option + Shift + =` | `Niri` | | Set Window Primary Span -10% / +10% | `Unassigned` | `Niri` | | Reset Window Secondary Span | `Control + Option + R` | `Niri` | | Cycle Window Primary Span Forward / Backward | `Unassigned` | `Niri` | | Cycle Window Secondary Span Forward / Backward | `Unassigned` | `Niri` | | Center Column | `Unassigned` | `Niri` | | Center Visible Columns | `Unassigned` | `Niri` | `Consume or Expel Window Left / Right` exist as automation-only actions. They are reachable from `omniwmctl` but never appear in Settings > Hotkeys, because they intentionally cannot be bound to a shortcut. The daily `Focus` and `Move` shortcuts adapt to the active layout and Niri orientation. In horizontal Niri orientation, `Move Left / Right` consumes or expels across columns while `Move Up / Down` reorders within a column. Vertical orientation rotates those roles: `Move Up / Down` consumes or expels across rows while `Move Left / Right` reorders within a row. #### Dwindle Groups Dwindle groups use the existing Focus and Move bindings, so there are no separate group shortcuts to memorize. Only the active member occupies the tile; the other members stay hidden and the clickable tab rail shows their order. | Goal | Default Shortcut | Behavior | |------|------------------|----------| | Focus another tile | `Option + Arrow Keys` | Left / Right are always spatial. Up / Down are spatial for a singleton tile. | | Select the next / previous tab | `Option + Down / Up Arrow` | Within a group, Down advances and Up goes back. At the group edge OmniWM tries a spatial tile, then the configured monitor transition, and wraps locally only when neither exit succeeds. | | Join a singleton into a tile or group | `Option + Shift + Arrow Keys` | Joins the focused singleton with the touching tile in that direction. | | Extract the active tab | `Option + Shift + Arrow Keys` | When the focused tile is grouped, extracts only its active tab onto the requested side. | | Move the complete tile or group | `Control + Option + Shift + Left / Right Arrow` | `Move Container` swaps the whole structure. Up / Down are advanced, unassigned Dwindle actions. | | Select an exact tab | Click its tab rail item | Reveals and focuses that member without changing the group order. | Moving a tab directly from one existing group into another is intentionally a two-step operation: extract it first, then move the resulting singleton toward the destination group. A singleton at a genuine workspace edge can still use the normal cross-monitor Move behavior; a rejected group mutation does not fall through to tile swapping or monitor movement. The unassigned advanced actions are available in Settings > Hotkeys. `Focus Down or Top / Up or Bottom` always wraps within the active Niri column or Dwindle group. `Reorder Window Up / Down` changes the active member's position by one without wrapping. `Move Container` is the whole-structure escape hatch and never transfers to another monitor at a workspace edge. Dwindle join/extract and Move Container operations are intentionally unavailable while Overview is open; leave Overview before changing a Dwindle tree. #### Quake Terminal (Inside Terminal) | Action | Shortcut | |--------|----------| | New Tab | `Cmd + T` | | Close Tab | `Cmd + W` | | Next Tab | `Cmd + Shift + ]` | | Previous Tab | `Cmd + Shift + [` | | Next Tab (Alt) | `Ctrl + Tab` | | Previous Tab (Alt) | `Ctrl + Shift + Tab` | | Select Tab 1-9 | `Cmd + 1-9` | | Split Pane (Horizontal) | `Cmd + D` | | Split Pane (Vertical) | `Cmd + Shift + D` | | Close Pane | `Cmd + Shift + W` | | Equalize Splits | `Cmd + Shift + =` | | Navigate Pane | `Cmd + Option + Arrow Keys` | ### Features #### Quake Terminal A true quake/sticky terminal powered by Ghostty's libghostty. The default Center position fades it in place; Top, Bottom, Left, and Right slide it in from that screen edge. - Toggle it from the global shortcut shown in `Keyboard Shortcuts` - Supports multiple tabs and splits within tabs - Tab and pane shortcuts are listed in **Quake Terminal (Inside Terminal)** - Mouse resize by dragging edges; `Option + drag` to move - Configure position, width and height as percentages of the monitor's available screen area, opacity, and background effect in Settings - Choose Standard Blur with an adjustable radius or native Regular Glass/Clear Glass; switching effects preserves the saved Standard Blur radius - Auto-hides on focus loss (optional) - Command-click an OSC 8 hyperlink to open `http`/`https` links in your default browser or `mailto` links in your mail app; other schemes are blocked OmniWM remembers one custom size and position. It reuses that frame when it fits the selected monitor; otherwise it uses the configured position and percentages. **Reset to Default Position** appears in Settings once a custom frame is in use. Quake Terminal loads Ghostty's normal configuration files and their included files, so font, theme, and other terminal preferences can be shared. OmniWM applies its Quake background opacity and effect afterward; configure those in **Settings → Quake Terminal**. #### Command Palette Quickly search windows, app menus, or clipboard history from one shared palette: - Open it from the global shortcut shown in `Keyboard Shortcuts` - Use `Tab` / `Shift + Tab` to cycle forward or backward through the available modes - Use `Cmd + 1` for `Windows`, `Cmd + 2` for `Menu`, and `Cmd + 3` for `Clipboard` - Type to search by substring; window-title matches rank first, followed by app-name and workspace-name matches - Menu results always show keyboard shortcuts when available - `Up` / `Down` move the selection - `Enter` activates the selected result - Windows from macOS-hidden apps remain searchable with a Hidden badge; selecting one unhides its app and focuses that exact window - In Windows mode, `Shift + Enter` summons the selected window to the right when available - In Clipboard mode, `Enter` copies the selected entry and pastes it into the previous app when that target is still available; `Shift + Enter` copies without pasting - `Escape` dismisses the palette Clipboard history starts disabled. Open Clipboard mode (`Cmd + 3`) and click **Enable**, or set `clipboard.historyEnabled = true` in `settings.toml`. History retains supported text, rich text, HTML, images, and file references within the configured limits; items marked concealed, transient, or autogenerated, including recognized password-manager markers, are skipped. Each row has Copy and Delete actions, and the trash button clears the history. See the [command palette guide](https://omniwm.app/features/command-palette/#clipboard-history) for storage details. #### Menu Anywhere Open the frontmost app's menus at your cursor with a global shortcut. Menu Anywhere builds a native floating menu from the menus, submenus, and shortcuts the app exposes through Accessibility. #### Overview Mode Overview supports [trackpad opening and closing](https://omniwm.app/features/overview/), with finger tracking when animations are enabled. See all windows at once with thumbnails: - Open it from the global shortcut shown in `Keyboard Shortcuts` - Configure the 50–150% baseline zoom plus backdrop and window-border colors in **Settings → Overview** - Click a window to focus it - Type to filter/search windows; `Backspace` deletes search text - `Alt (Option) + Shift + Mouse Scroll` temporarily zooms the current overview; the next opening starts from the configured baseline - `Arrow Keys` navigate spatially; `Left` / `Right` stay within the current workspace. `Tab` / `Shift + Tab` cycle forward or backward through matching windows, and keyboard navigation automatically scrolls the selected thumbnail into view - Assigned structural move, reorder, consume/expel, and workspace-transfer shortcuts operate on the selected thumbnail while Overview is open - In Niri workspaces, reorder windows and columns, consume or expel windows, move windows into or out of columns, move windows across workspaces and monitors, and move whole columns between Niri workspaces - Adjacent-workspace fallback actions can create the next compatible unused numeric workspace when moving past the current workspace edge - In Dwindle workspaces, Overview supports moving windows across workspaces and closing them without adding Overview-only tree placement controls - A successful move keeps the moved window selected and activates its destination workspace and monitor behind Overview - Drag a thumbnail onto a workspace, an exact window position, or a Niri column gap; layouts without an exact placement equivalent fall back to moving it to the destination workspace. Press and release without dragging to focus it - `Command + W` closes the selected window once per press and keeps Overview open; selection advances only after the window has closed - `Enter`, `Escape`, the configured Overview shortcut, and clicking the backdrop dismiss Overview and focus the current selection; `Escape` does not clear search first - If another application takes focus, Overview dismisses without stealing focus back #### Workspace Bar A visual indicator showing your workspaces: - Displays open apps per workspace - Click to switch workspaces or jump to that app - When `Deduplicate App Icons` is enabled, multiple windows from one app share an icon; click a grouped icon to open their window list, while a single-window icon focuses that window directly - Marks macOS-hidden windows with an eye-slash badge; selecting a hidden window unhides its app and focuses that exact window - Configure position, height, and appearance in Settings - Optionally show a System Stats button that opens a CPU, memory, GPU, disk, and uptime popup. `Toggle System Stats` and `omniwmctl command toggle-system-stats` drive the same popup, and both do nothing unless a monitor currently shows that workspace-bar button - Optionally hide the bar on a monitor while that monitor shows a macOS native fullscreen window, and bring it back on exit (`Hide in Native Fullscreen`); reserved tiled layout space is left untouched so windows do not shuffle around the fullscreen session - Exclude individual apps or choose alternate app icons across all monitors in Settings Workspace-bar appearance controls are optional and also support per-monitor overrides: - **Transparent Background** removes the outer bar material, tint, and border; icons remain clickable. It takes precedence over **Solid Black Background**. - **Solid Black Background** uses opaque black instead of the outer bar's material and tint. - **Inactive Icon Opacity** adjusts non-focused app icons. Leaving it unset preserves the standard opacity for each kind of item; hidden-app icons retain their hidden-state appearance. Values are limited to 0–1, and nonfinite values are treated as unset. - Disable **Show Item Backgrounds** to remove the backgrounds behind workspace groups, floating windows, scratchpads, and the stats button. - Disable **Show Accent Highlights** to remove focused-item accent outlines and glows without changing focus behavior. - **Fill Left of Notch** covers the menu-bar band from the display's left edge to the notch, or to the display midpoint when no notch is present. This deliberately covers application menus; choose another notch mode to access them again. This mode uses the menu-bar height, ignores position/offset/height controls, and does not reserve extra tiled layout space. It always hides on displays showing native fullscreen content; other modes continue to follow **Hide in Native Fullscreen**. Existing appearance stays unchanged until you opt in. For example, edit these keys inside the existing `[workspaceBar]` table (do not replace the complete configuration with this fragment): ```toml transparentBackground = false solidBlackBackground = true inactiveIconOpacity = 0.9 showItemBackgrounds = false showAccentHighlights = false notchMode = "fillLeftOfNotch" ``` These optional settings keep configuration schema 3. Omitted keys preserve the existing appearance without migrating the settings file. Workspace-bar icon overrides can also be configured in `settings.toml`. Quote bundle IDs so TOML treats each dotted identifier as one key: ```toml [workspaceBar.iconOverrides] "com.example.App" = "icons/custom.icns" "com.cmuxterm.app" = "bundle-resource:AppIconDark" ``` `bundle-resource:` loads a named image packaged inside the selected app. The Settings picker discovers likely app-icon resources on demand; runtime-generated or downloaded Dock icons may not be available. Absolute paths are used as written, `~` expands to your home directory, and relative paths are resolved from the directory containing `settings.toml`. Overrides affect only the workspace bar. A valid override takes precedence over the app's standard icon; an unavailable or invalid image falls back to the standard icon, then the dashed placeholder when no app icon is available. OmniWM does not watch image files; use Replace to reload a file changed in place. #### Hidden Bar Conceal selected menu-bar icons and reach them from a panel: - Concealment requires macOS 27 or later; core window management supports macOS 26 - Pick the apps to hide in `Settings > Hidden Bar` - Right-click (or Option-click) the OmniWM menu bar icon to open the Hidden Icons Bar; click an icon to reveal and use it - Revealed icons re-hide automatically after a configurable interval - An optional global hotkey is available and starts unassigned ### Tips - **Workspaces** - Create named workspaces in Settings to organize by project or context (You can use emojis 🥳) - **App Rules** - Exclude problematic apps from tiling or assign them to specific workspaces - **Mouse** - Hold the configured mouse-move modifier and drag to swap tiled windows. Niri swaps individual windows; add `Shift` to insert into a column. Dwindle swaps whole tiles, including their tab groups. The modifier defaults to `Option` and can be changed or disabled in **Settings → Mouse & Trackpad**. In Overview, dragging a thumbnail needs no modifier and targets a workspace, window position, or Niri column gap - **Mouse Resize** - Hold the configured right-mouse resize modifier (`Option` by default) and right-drag a tiled window to resize it in either layout - **Scroll Gestures (Mouse)** - Hold `Option + Shift + Mouse Scroll Wheel` (default, configurable) to scroll along the active Niri primary axis: left/right in horizontal orientation or up/down in vertical orientation - **Trackpad Gestures** - Use 2/3/4-finger gestures (configurable) along the active Niri primary axis; direction can be inverted - **Window Move & Resize (Trackpad)** - Opt-in in Settings → Mouse & Trackpad: drag without clicking to move or resize the tiled window under the cursor in either layout; lift your fingers to drop. Defaults are four fingers to move and three to resize. Column scrolling is on by default with three fingers, so the Resize row first offers **Set Up…**; pick another finger count (two fingers can intercept normal scrolling in apps) or turn off **Scroll columns**. Choose finger counts unused by other enabled gestures; **Set Up…** previews conflicts and lets you choose which gestures to turn off before applying the assignment. Turn off matching macOS gestures in System Settings → Trackpad → More Gestures to prevent them firing alongside window gestures. - **Workspace Swipe (Trackpad)** - Opt-in in Settings → Mouse & Trackpad: swipe with a configurable finger count (2/3/4) and axis (horizontal/vertical) to switch to the next/previous workspace on the monitor under the cursor, one switch per swipe; when sharing fingers with enabled column scrolling in Niri, workspace swipes use the perpendicular axis on each display; otherwise they use the selected axis. For vertical swipes with three or four fingers, first turn off Mission Control in  → System Settings → Trackpad → More Gestures so macOS does not intercept the gesture. ## Configuration Access settings by clicking OmniWM's status bar icon and selecting **Settings** or **App Rules**. Mouse and gesture settings live in Settings under **Mouse & Trackpad**. The **Trackpad Gestures** panel shows all five assignments together. Finger selectors work while a gesture is off; **Set Up…** explains conflicts and offers explicit reassignment choices before turning anything off. Expand a gesture row for its additional controls. **Settings > General** also carries a **System-wide Window Corners** control (macOS 26.4+). It writes the system-wide preference, so it changes standard Mac app windows everywhere — including windows OmniWM does not manage — and apps that draw their own window chrome may ignore it. Affected apps must be fully quit and reopened before the new radius applies. OmniWM stores its editable config at `${XDG_CONFIG_HOME:-$HOME/.config}/omniwm/settings.toml`; that file is the canonical settings source and is live-reloaded when saved from an editor. `XDG_CONFIG_HOME` and `XDG_STATE_HOME` are honored only when set to absolute paths; otherwise OmniWM uses `~/.config` and `~/.local/state`, respectively. Most configuration is also editable in Settings. **Start at Login** is managed by macOS, and **System-wide Window Corners** changes a macOS preference; neither is stored in `settings.toml`. Clipboard retention limits and scratchpad labels are edited in TOML. - **Reveal Settings File** and **Edit Settings File** open the canonical TOML file and recreate it from the running settings if it was deleted. - `updateChecksEnabled` is part of the persisted settings model, so it round-trips through `settings.toml`. - Clipboard history, last-check timestamps, skipped-release state, and the persisted window restore catalog live in `${XDG_STATE_HOME:-$HOME/.local/state}/omniwm` and stay out of dotfile-oriented config storage. ## Scratchpads A scratchpad is a slot that holds any number of floating windows and overlays them on the workspace you are looking at. There are ten slots, numbered 1 to 10; a slot with no windows in it is inert and invisible. - **Assign Focused Window to Scratchpad N** moves the focused window into slot N, floating it if it was tiled. It stays visible if slot N is already revealed; otherwise it is parked off-screen. Pressing the same shortcut again on a window already in slot N returns it to the layout. - **Toggle Scratchpad N** reveals eligible windows in slot N on the monitor you are interacting with, or parks them again if they are already there. Revealing a slot parks whichever slot was showing, so at most one scratchpad is on screen at a time. - A revealed scratchpad follows you across workspace switches and stays up until you toggle it off. If it is showing on another monitor, its shortcut summons it to the one you are on. - Revealed windows are ordinary floating windows: whether clicking something underneath pushes them behind it is governed by the usual focus and raise behaviour, including **Raise Window When Focus Follows Mouse**. Hotkey and CLI toggles leave macOS-hidden apps hidden and skip windows suspended in native fullscreen. Clicking a workspace-bar pill while the slot is hidden can unhide its apps; exit native fullscreen before revealing a suspended window. Each non-empty slot gets a pill in the workspace bar showing its name and its windows' icons; clicking the pill toggles that scratchpad. Slots are identified by number everywhere, and an optional label replaces the number in the workspace bar and in `omniwmctl` output: ```toml [scratchpads.labels] 1 = "term" 3 = "COMMS" ``` Scratchpad membership lasts for the lifetime of the OmniWM process; only the labels are persisted. ## App Rules Open **App Rules** from OmniWM's status-bar menu to configure window-matching behavior. Rules can match by bundle ID, app-name substring, title substring or regex, and AX role/subrole. More-specific matches win; ties follow list order. - **Layout (Automatic / Tile / Float)** - Leave classification automatic, or force matching windows to tile or float - **Assign to Workspace** - Use a valid workspace assignment as the initial default whenever the matching app currently has no tracked windows. Additional windows open on the workspace active when creation began. Automatic rule reevaluation leaves managed windows in place, while explicit rule application can move them. Readmission, structural replacements, and unique persisted boot-restore matches preserve their existing placement continuity. - **Initial Container Primary Span (Niri)** - Start matching resizable windows at 5–100% when they create or claim a new container; the container remains freely resizable afterward - **Minimum Size** - Prevent the layout engine from sizing windows below a threshold Structural admission runs before ordinary rule ranking. Help tags, input-method surfaces, and WindowServer children of another window stay unmanaged. At ordinary WindowServer levels, a closeable, parentless accessory-app `AXWindow` is eligible for normal classification. Buttonless accessory roots, prohibited-app roots, non-`AXWindow` roles, and otherwise unsupported AX subroles require an identifying rule with exact `axRole` and `axSubrole` values plus a Tile or Float layout. Parentless roots at status-window level or higher use the same precise shape, but only a user rule can opt them in; built-in rules cannot. A broad bundle/title rule or Automatic layout does not cross these gates. Initial container primary span is a one-time seed. It controls width in horizontal orientation and height in vertical orientation. Niri's Single Window Fit still takes visual precedence for a lone window, and physical minimum-size constraints can clamp the resolved pixel size without changing the stored initial proportion. The equivalent TOML rule uses a proportion: ```toml [[appRules]] bundleId = "net.kovidgoyal.kitty" initialContainerPrimarySpan = 0.5 ``` ## Building from Source Follow the [contributor quick start](CONTRIBUTING.md#quick-start) for Xcode requirements, automatic dependency setup, and a separate **OmniWM Dev** app with independent settings. The guide covers rebuilding, switching back to your normal app, and verifying a pull request. ## Community Integrations - **[omacosy](https://github.com/paulsp94/omacosy)** is an Omarchy-inspired macOS desktop setup that supports OmniWM as a tiling window manager, with a custom status bar and coordinated desktop themes. - **[OmniWM Computer Use](https://github.com/nick-s5/omniwm-computer-use)** is a community-maintained Codex skill for focus-safe Computer Use, browser automation, and app testing through `omniwmctl` across OmniWM workspaces and displays. - **[OmniCast](https://github.com/imprisonedmind/omni-cast)** is a community-maintained Raycast extension for controlling OmniWM with plain-English search and commands through `omniwmctl`. ## Related Forks - **[Nehir](https://github.com/apphane-dev/nehir)** is an endorsed OmniWM fork focused on a narrower, more opinionated Niri-style scrolling-column workflow. It may be friendlier for beginners who want guided defaults and a smaller feature surface, while OmniWM remains the broader upstream project with multiple layout modes and the full feature set. - **[choru-k/OmniWM](https://github.com/choru-k/OmniWM)** is an interesting personal OmniWM fork experimenting with opt-in workflow layers on top of upstream OmniWM, including zone anchors for the Niri strip, a configurable F13-F20 leader-key chord menu, tabbed-column keyboard cycling, and trackpad-friendly modifier resizing. It is best read as a power-user workflow branch rather than a replacement for the main OmniWM release. ## Community Questions, setup help, and config sharing happen on the [OmniWM Discord](https://discord.gg/NFrJKNmmrT). Confirmed bugs still belong on GitHub — see [Reporting Bugs](#reporting-bugs). Community integrations and related forks are listed above and on the [Community & Support](https://omniwm.app/help/community/) page. ## Support If you find OmniWM useful, consider supporting development: - [GitHub Sponsors](https://github.com/sponsors/BarutSRB) - [PayPal](https://paypal.me/beacon2024) ## Reporting Bugs The best way to report a bug is from inside OmniWM: open the status-bar menu and choose **Report a Bug…**. That opens the in-app report form, where recording or attaching trace and crash evidence is optional. On submit, OmniWM prepares one fresh diagnostic `.log` (with any evidence you selected appended), reveals it in Finder for you to attach, and opens a pre-filled GitHub issue — OmniWM never sees your GitHub login. Review the `.log` before attaching it to a public issue: it can include settings, app and window titles, and title-based rule matchers. Prefer the web? The [GitHub issue form](https://github.com/OmniNull/OmniWM/issues/new/choose) works too; please include your OmniWM and macOS versions there. ## Contributing Issues and pull requests are welcome on [GitHub](https://github.com/OmniNull/OmniWM). Start with [CONTRIBUTING.md](CONTRIBUTING.md) for the actual project guidelines, expectations, and preferred direction. For deeper technical context, edit the source pages used by the documentation site: - [Architecture Guide](website/src/content/docs/developers/architecture.md) - [IPC & CLI Reference](website/src/content/docs/reference/cli/overview.md) - [Contribution Docs](website/src/content/docs/developers/contributing.md) The similarly named files under `docs/` are compatibility stubs that direct old links to `omniwm.app`. ## License OmniWM is licensed under the [GNU General Public License v2.0-only](LICENSE). Copyright (C) 2026 BarutSRB — https://github.com/OmniNull/OmniWM. Every source file carries an SPDX license header. Forks and redistributions must retain these notices and the `LICENSE` file, and remain GPL-2.0-only with source available.