--- title: "Omarchy" url: "https://docs.phux.sh/omarchy" source: "https://github.com/no-phux/phux/blob/24fce1b6c7321c429fd4b68f2c7a4d1d3e55adbd/docs/omarchy.md" projectVersion: "0.113.1" protocolVersion: "1.0.0" stability: "stable" --- # Omarchy Omarchy is an Arch Linux and Hyprland desktop setup. One command puts phux in the places Omarchy keeps a terminal multiplexer: ```sh phux omarchy setup ``` Then: | Press | Does | | --- | --- | | Super Ctrl Return | Opens a terminal attached to phux | | Super Ctrl K | Lists phux's keys in Omarchy's menu | Inside phux, the keys are the ones Omarchy's tmux config uses, so your hands already know them. Switch Omarchy's theme and phux repaints to match. ## What setup changes `phux omarchy setup` is safe to run again. It prints every file it writes, and `--dry-run` prints them without writing anything. | Change | Where | | --- | --- | | A [distro](/distros) layer with Omarchy's tmux keys, selected in your config. A distro you already had selected stays underneath it. | `~/.local/share/phux/distros/omarchy/omarchy.toml` | | phux follows Omarchy's current theme, unless your config already selects a theme. | `[theme] file` in your config | | A hook that repaints phux after each Omarchy theme change. | `~/.config/omarchy/hooks/theme-set.d/phux` | | Super Ctrl Return and Super Ctrl K open phux and its key list. | A marked block in `~/.config/hypr/bindings.lua` | | The phux server starts with your desktop session, so its panes can reach the Wayland clipboard even when you first attach over SSH. | A marked block in `~/.config/hypr/autostart.lua` | Omarchy gives Super Ctrl Return and Super Ctrl K to Herdr out of the box; setup rebinds them to phux. Omarchy's tmux keys, Super Alt Return and Super Alt K, are left alone. setup never edits text outside its marked blocks: ```lua -- >>> phux: managed by `phux omarchy setup`; `phux omarchy remove` deletes it o.rebind("SUPER + CTRL + RETURN", "Phux", "omarchy-launch-terminal /home/you/.local/bin/phux") o.rebind("SUPER + CTRL + K", "Phux keybindings", [[sh -c '/home/you/.local/bin/phux omarchy keys | omarchy-menu-select "Phux keybindings" -- --width 800']]) -- <<< phux ``` The blocks name the phux binary by its full path, because Hyprland's `PATH` may not include `~/.local/bin`. If you move phux, for example from the install script to a package, run setup again. An Omarchy that still uses `hyprland.conf` gets the same blocks in `bindings.conf` and `autostart.conf`. Check what's in place: ```text $ phux omarchy status ✓ omarchy ✓ distro ✓ theme ✓ theme_hook ✓ desktop_keys ✓ autostart ``` ## Keys The prefix is Ctrl Space, as in Omarchy's tmux. A tmux window is a phux tab, and a tmux session is a phux session. | Key | Does | | --- | --- | | Alt Enter | Split below | | Alt Shift Enter | Split right | | Alt Esc | Kill pane | | Ctrl Alt ←↓↑→ | Move between panes | | Ctrl Alt Shift ←↓↑→ | Resize the pane | | Alt 1 … 9 | Go to tab 1 to 9 | | Alt ← / → | Previous / next tab | | Alt Shift ← / → | Move the tab left / right | | Alt ↑ / ↓ | Previous / next session | | prefix h / v | Split below / right | | prefix c / r / k | New / rename / kill tab | | prefix C / R / K | New / rename / kill session | | prefix P / N | Previous / next session | | prefix q | Reload the config | | prefix ? | Every command, searchable | Everything else keeps phux's [default keys](/reference/keys). Three moved to make room for tmux's: prefix a jumps to the next pane waiting for you (phux's prefix q), resizing uses Ctrl Alt Shift and the arrows instead of prefix R, and Ctrl Alt and the arrows move between panes instead of prefix h and k. `phux omarchy keys` prints every key in effect, your own bindings included, one per line. That is the list Super Ctrl K shows. ## Your settings still win The layer sits under your own `config.toml`, so any key you set there wins. To change one of the keys above, bind it in your config: ```toml [keybindings.prefix-table] "q" = "next-attention" ``` To keep the opaque status bar and sidebar of phux's own theme instead of letting the terminal's background show through, set the [theme slot](/themes#overriding-one-colour): ```toml [theme] surface = "#1a1b26" ``` Setup rewrites the layer each time it runs. Put changes in your config, not the layer. ## Themes phux reads Omarchy's `colors.toml` as it is, so its sidebar, status bar, pane borders and popups use the theme's colours. When you switch themes, Omarchy runs the `theme-set` hook, which runs `phux config reload`, and attached clients repaint without detaching. Programs inside your panes use your terminal's colours, which Omarchy changes itself. If your config already selected a theme before setup, setup keeps it and tells you. To follow Omarchy's theme afterwards: ```sh phux theme set --file ~/.local/state/omarchy/current/theme/colors.toml ``` ## Undo it ```sh phux omarchy remove ``` This restores the distro you had selected before setup, stops following Omarchy's theme if setup turned that on, and deletes the hook, the layer and the marked Hyprland blocks. Everything else in those files is left as it was. Omarchy's own bindings for Herdr come back when Hyprland reloads.