BarutSRB/Hiro

## Demo Video [](https://youtu.be/WcHjGkuD2Fc) ## Known Limitations - **Gestures/Trackpad** - Magic Mouse and trackpad gestures are untested (no hardware available for testing but haven't heard complaints so it works) ## Performance & Trust OmniWM is built for high responsiveness and smooth, crisp animations. - **Private APIs** - OmniWM leverages Apple's private APIs where ever technically possible in order to reduce latency and improve window management responsiveness. - **Refresh rate aware animations** - OmniWM targets true display refresh pacing (for example 60/120/144Hz) for animations. - **No SIP disable required** - OmniWM does not require System Integrity Protection (SIP) to be disabled and never will. - **Always notarized official releases** - Official OmniWM release builds are developer signed and notarized by Apple and will stay that way. - **Forever free, no limitations** - OmniWM is and will remain free to use forever, with no subscriptions, feature paywalls, trial limits, or usage caps. ## Requirements - macOS 15+ (Sequoia) - Accessibility permissions (prompted on launch) - Input Monitoring permission for leader-key, multi-key sequence, or custom Hyper key shortcuts - Displays have separate spaces **OFF** ## Installation ### Homebrew brew tap BarutSRB/tap brew install omniwm ### GitHub Releases 1. Download the latest `OmniWM.zip` from [Releases](https://github.com/BarutSRB/OmniWM/releases) 2. Extract and move `OmniWM.app` to `/Applications` 3. In System Settings > Desktop & Dock > Mission Control, turn **OFF** `Displays have separate Spaces` 4. Log out of macOS and log back in for that change to take effect unless you had it off already 5. Launch OmniWM and grant Accessibility permissions when prompted 6. For leader-key, multi-key sequence, or custom Hyper key shortcuts, grant Input Monitoring from Settings > Hotkeys ## 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 documentation hub lives in [`docs/index.md`](docs/index.md). - [Documentation Home](docs/index.md) - [Architecture Guide](docs/ARCHITECTURE.md) - [IPC & CLI Reference](docs/IPC-CLI.md) - [Contribution Docs](docs/CONTRIBUTING.md) - [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. For setup, installation options, commands, queries, rules, subscriptions, and security details, see [docs/IPC-CLI.md](docs/IPC-CLI.md). ## Quick Start 1. Launch OmniWM from your Applications folder 2. In System Settings > Desktop & Dock > Mission Control, turn **OFF** `Displays have separate Spaces` 3. Log out of macOS and log back in for that change to take effect unless you had it off already 4. Grant Accessibility permissions in System Settings > Privacy & Security > Accessibility 5. Windows will automatically tile in columns 6. Use the default shortcuts in `Keyboard Shortcuts` to navigate between windows 7. Click the menu bar icon to access Settings, including `Settings > General > Updates` 8. Use `Check for Updates...` from the status bar menu whenever you want to run a manual update check 9. In case you freak out and don't see all your status bar icons, relax, right click on OmniWM's status bar icon and drag the icons to the left of it's "/" by holding CMD + drag as OmniWM hides status bar icons like **Ice Bar**. ## User Guide ### Layout Modes OmniWM offers two layout engines that you can switch between per workspace: **Niri (Scrolling Columns)** - Windows arranged in vertical columns that scroll horizontally. Each column can have multiple stacked windows or be "tabbed" (multiple windows, one visible at a time). Best for wide monitors with many windows. **Hyprland Dwindle (BSP)** - Binary space partition layout that recursively divides screen space. Each new window splits the space in half. 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. Single-key chords, `Hyper` chords, leader-key sequences, and presets are configured there. `Hyper` defaults to Control + Option + Shift + Command, the leader key defaults to `Hyper + Space`, and Caps Lock can be enabled as a power-user Hyper preset. Vim Navigation is opt-in because leader-key sequences need Input Monitoring permission. 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. #### Workspace | Action | Default Shortcut | Layout | |--------|------------------|--------| | Switch to Workspace 1-9 | `Hyper + 1-9` | `Shared` | | Move Window to Workspace 1-9 | `Option + Shift + 1-9` | `Shared` | | Switch to Previous 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 Previous Window | `Option + Tab` | `Niri` | | 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` | | Toggle Command Palette | `Control + Option + Space` | `Shared` | | Open Menu Anywhere | `Control + Option + M` | `Shared` | | Toggle Workspace Bar | `Unassigned` | `Shared` | | Toggle Hidden Bar | `Unassigned` | `Shared` | | Toggle Quake Terminal | `` Option + ` `` | `Shared` | | Toggle Overview | `Option + Shift + O` | `Shared` | #### Move Window | Action | Default Shortcut | Layout | |--------|------------------|--------| | Move Left / Right / Up / Down | `Option + Shift + Arrow Keys` | `Shared` | #### Monitor | Action | Default Shortcut | Layout | |--------|------------------|--------| | Focus Next Monitor | `Control + Command + Tab` | `Shared` | | Focus Previous Monitor | `Unassigned` | `Shared` | | Focus Last Monitor | `` Control + Command + ` `` | `Shared` | #### Layout | Action | Default Shortcut | Layout | |--------|------------------|--------| | Toggle Fullscreen | `Option + Return` | `Shared` | | Toggle Native Fullscreen | `Unassigned` | `Shared` | | Balance Sizes | `Option + Shift + B` | `Shared` | | Move to Root | `Unassigned` | `Dwindle` | | Toggle Split | `Unassigned` | `Dwindle` | | Swap Split | `Unassigned` | `Dwindle` | | Grow Left / Right / Up / Down | `Unassigned` | `Dwindle` | | Shrink Left / Right / Up / Down | `Unassigned` | `Dwindle` | | Preselect Left / Right / Up / Down | `Unassigned` | `Dwindle` | | Clear Preselection | `Unassigned` | `Dwindle` | | Raise All Floating Windows | `Option + Shift + R` | `Shared` | | Toggle Focused Window Floating | `Unassigned` | `Shared` | | Assign Focused Window to Scratchpad | `Unassigned` | `Shared` | | Toggle Scratchpad Window | `Unassigned` | `Shared` | | Toggle Workspace Layout | `Option + Shift + L` | `Shared` | #### Column | Action | Default Shortcut | Layout | |--------|------------------|--------| | Move Column Left / Right | `Control + Option + Shift + Left / Right Arrow` | `Niri` | | Toggle Column Tabbed | `Option + T` | `Niri` | | Cycle Column Width Forward | `Option + .` | `Shared` | | Cycle Column Width Backward | `Option + ,` | `Shared` | | Toggle Column Full Width | `Option + Shift + F` | `Niri` | In Niri, `Move Left / Right` expels the focused window out of multi-window columns or consumes a single-window column into the adjacent column. `Move Up / Down` keeps the current in-column reorder behavior. #### 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) that slides in from the screen edge and: - 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 (remembers size/position per monitor) - Configure position (top/bottom/left/right/center), size, and opacity in Settings - Auto-hides on focus loss (optional) #### Command Palette Quickly search windows or app menus from one shared palette: - Open it from the global shortcut shown in `Keyboard Shortcuts` - Use `Cmd + 1` for `Windows` and `Cmd + 2` for `Menu` when menu search is available - Type to fuzzy-search by window title, app name, or menu item - Menu results always show keyboard shortcuts when available - `Up` / `Down` move the selection - `Enter` activates the selected result - `Shift + Enter` summons the selected window to the right when available - `Escape` dismisses the palette #### Menu Anywhere Access any application's menu from your keyboard: - Shows the native menu at the cursor from a global shortcut #### Overview Mode See all windows at once with thumbnails: - Open it from the global shortcut shown in `Keyboard Shortcuts` - Click a window to focus it - Type to filter/search windows; `Backspace` deletes search text - Alt + Shift + Mouse Scroll to zoom in/out - `Arrow Keys` navigate the selection; `Tab` / `Shift + Tab` move horizontally - `Enter` activates the selected window - `Escape` clears the search first, then dismisses the overview when the search is empty #### Workspace Bar A visual indicator showing your workspaces: - Displays open apps per workspace - Click to switch workspaces or jump to that app - If dedupe option is on click the app icon to get a popup with list of all its windows to jump to - Configure position, height, and appearance in Settings #### Hidden Bar Hide or reveal status bar icons using a separator item: - Right-click the OmniWM menu bar icon to toggle - 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** - `Option + drag` swaps tiled windows; `Option + Shift + drag` inserts windows to a column (Niri) - **Mouse Resize** - Hold `Option` and right-drag a tiled window to resize (Niri) - **Scroll Gestures (Mouse)** - Hold `Option + Shift + Mouse Scroll Wheel` (default, configurable) and scroll through columns horizontally - **Trackpad Gestures** - Use horizontal gestures with 2/3/4 fingers (configurable); direction can be inverted (not tested lacking hardware) ## Configuration Access settings by clicking OmniWM's status bar icon and selecting **Settings** or **App Rules**. Mouse and gesture settings are available in Settings. 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. - **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, hidden bar state, and the persisted window restore catalog live in `${XDG_STATE_HOME:-$HOME/.local/state}/omniwm` and stay out of dotfile-oriented config storage. ## App Rules Configure per-application behavior in Settings > App Rules: - **Always Float** - Force specific apps to always float (e.g., calculators, preferences windows) - **Assign to Workspace** - Open first matching app windows on a specific workspace; later windows follow the app's current workspace unless rules are explicitly applied - **Minimum Size** - Prevent the layout engine from sizing windows below a threshold ## Building from Source Requirements: - SwiftPM with Swift 6.3.2+ - macOS 15.0+ - Ghostty's universal `libghostty.a` (build Ghostty and copy it to `Frameworks/GhosttyKit.xcframework/macos-arm64_x86_64/libghostty.a` so it includes both `arm64` and `x86_64`)