# Omarchy — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT # Omarchy Knowledge Base An LLM-maintained knowledge base on **Omarchy** (github.com/basecamp/omarchy, omarchy.org) — DHH/Basecamp's 'Beautiful, Modern & Opinionated Linux': a curated Arch Linux + Hyprland desktop with a keyboard-driven workflow, unified menu, theming system, and dev tooling out of the box. Pinned to v4.0.0. ## Concepts - [[concepts/omarchy-overview|Omarchy Overview]] - [[concepts/installation|Installation]] - [[concepts/coming-from-mac-or-windows|Coming From Mac or Windows]] - [[concepts/navigation-and-hotkeys|Navigation and Hotkeys]] - [[concepts/the-menu|The Menu]] - [[concepts/theming|Theming]] - [[concepts/hyprland-and-window-management|Hyprland and Window Management]] - [[concepts/monitors-and-hardware|Monitors and Hardware]] - [[concepts/omarchy-cli-and-shell|Omarchy CLI and Shell]] - [[concepts/terminal-and-neovim|Terminal and Neovim]] - [[concepts/ai-and-dev-tools|AI and Development Tools]] - [[concepts/tuis-guis-and-browsers|TUIs, GUIs, and Browsers]] - [[concepts/apps-and-services|Apps and Services]] - [[concepts/productivity-tools|Productivity Tools]] - [[concepts/system-management|System Management]] - [[concepts/security|Security]] - [[concepts/plugins-and-extension|Plugins and Extension]] - [[concepts/tweaks-troubleshooting-and-faq|Tweaks, Troubleshooting, and FAQ]] ## Summaries - [[summaries/release-digest|Release Digest]] --- title: "AI and Development Tools" type: concept tags: [apps, system, security, power-user, advanced] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-manual-17-ai-md.md", "raw/github_doc-manual-18-development-tools-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- ## Definition Omarchy treats AI coding agents as first-class, pre-wired citizens without picking a favorite, and pairs that with a broad development environment: most language/runtime toolchains via [mise](https://mise.jdx.dev/), plus menu-installed alternative editors, a separately-managed Docker setup, and `gh`/`ghui` as lazy-loading mise stubs. Together these make Omarchy a machine that's ready to code — and to hand code-writing off to an agent — with minimal setup. ## How It Works ### AI coding agent launchers Every major coding-agent CLI is pre-wired as a lazy-loaded launcher — tiny mise-managed stubs in `~/.local/bin/` that download nothing until first invoked: | Command | Agent | |---------|-------| | `claude` | Claude Code | | `codex` | OpenAI Codex | | `opencode` | OpenCode | | `agy` | Google Antigravity CLI | | `copilot` | GitHub Copilot CLI | | `crush` | Crush | | `grok` | Grok CLI (xAI) | | `pi` | Mario Zechner's Pi | | `omp` | Oh My Pi | | `ori` | Ori, OpenRouter's harness | `ori` is the odd one out: it runs the *other* harnesses against OpenRouter's model catalog (`ori claude`, `ori codex`, `ori opencode`), while `ori code` is Ori's own agent. To wrap an additional CLI the same lazy-loading way, run `omarchy-mise-install [command-name]` — see [[concepts/omarchy-cli-and-shell]] for how `omarchy update`/`mup` keeps all mise-managed stubs current. ### Choosing and launching a default agent `omarchy default agent ` (or _Setup > Defaults > Agent_ in the Omarchy menu) sets the default; picking an agent that isn't installed installs it first, and a fresh Omarchy prompts for this choice once via a first-run notification. `Super + Shift + Ctrl + A` launches the default agent in a dedicated terminal window (or opens the picker if none is chosen yet); `omarchy agent prompt "Review this project"` launches it straight into a task. Terminal shortcuts: `a` runs the default agent inline in the current terminal, while `c`, `cx`, and `cy` start OpenCode, Claude Code, and Codex directly. **Agents launched this way run unattended, in their auto-approving / don't-stop-to-ask modes** — the manual explicitly flags this as something to be ready for. Because agents refuse to accept trust for the home directory, a launch from `$HOME` starts in `~/Work` instead. Theme changes propagate live to agents that support it: Claude Code, Pi, and OpenCode all follow the system theme when it's switched (see [[concepts/theming]]). ### The agents panel The top bar grows an agents icon the first time Omarchy detects AI coding usage on the machine (and stays hidden until then). Left-click for the panel, right-click to launch the default agent. It tracks every subscription in one place: plan, percentage used of the 5-hour session and weekly limits (or remaining prepaid balance), and token usage by day and model — covering Claude Code, Codex, and Fireworks out of the box. The underlying usage records regenerate every 15 minutes via `omarchy agent usage-update`, and can merge usage from other machines through a synced folder (full settings documented under `$OMARCHY_PATH/shell/plugins/agents/`). ### Crash diagnosis Omarchy watches systemd-coredump for process crashes. A "Process crashed" notification, when clicked, hands the crash to the default agent along with Omarchy's built-in diagnose-crash skill, walking it through establishing facts from the core dump and deciding whether the crash is worth reporting upstream. `omarchy agent crash ` runs the same flow by hand against any PID from `coredumpctl list`. The watcher is on by default; turn it off under _Trigger > Toggle > Crash Capture_ or `omarchy toggle crash-capture` (see [[concepts/productivity-tools]] for the general toggle pattern) — manual invocation via `omarchy agent crash ` still works either way. ### Desktop AI apps and local LLMs _Install > AI_ in the Omarchy menu also carries graphical apps: the ChatGPT desktop app and Grok Bot. For running models locally, Omarchy recommends **LM Studio** (GUI, good starting point for newcomers to local models — find, install, and run open-weight models) and **Ollama** (CLI-based equivalent); both install from _Install > AI_. ### The Omarchy Skill Agent skills teach an AI how to use a specific tool in a specific way, and Omarchy ships a default skill for tailoring the system itself — adjusting Hyprland config, the bar, or even creating a new theme from scratch. It's symlinked into the skill directories of Claude Code (`~/.claude/skills`), Codex (`~/.codex/skills`), Pi (`~/.pi/agent/skills`), Antigravity (`~/.gemini/config/skills`), and the generic `~/.agents/skills`, so most harnesses pick it up automatically. It is explicitly labeled **experimental** — effectiveness varies by model — and the manual recommends running in plan mode first to preview changes, staying ready to roll back, and using `omarchy reinstall configs` if an agent makes a mess of the system. ### Alternative editors Neovim ships by default (see [[concepts/terminal-and-neovim]]), but _Install > Editor_ in the Omarchy menu offers VSCode, Cursor, Zed, Sublime Text, Helix, Vim, and Emacs. Anything not listed is worth checking under _Install > Package_ (official Arch repo) and then _Install > AUR_. Theme matching is offered specifically for VSCode, Cursor, VSCodium, and Helix. The system-wide default editor (what `Super + Shift + N` opens) is set under _Setup > Defaults > Editor_. ### Development environments via mise _Install > Development_ covers a very broad language/framework selection: Ruby on Rails; all three major JavaScript runtimes (Node.js, Bun, Deno); PHP frameworks (Laravel, Symfony); Go, Rust, Python, Java, Elixir (with Phoenix), .NET, OCaml, Zig, Clojure, and Scala. Most of these are managed by [Mise](https://mise.jdx.dev/), a single tool for installing and running multiple versions of many languages side by side (like rbenv/rvm for Ruby or virtualenv for Python, generalized). `mise use -g ruby` installs Ruby and sets it as the global default; `mise i` run inside a project with a version file (e.g. `.ruby-version`) installs exactly what that project needs. ### Docker Omarchy installs Docker and Docker Compose, but deliberately does **not** add the user to the `docker` group by default. That group is effectively passwordless root — anything in it can `docker run -v /:/host` and take over the machine — so a single rogue script running as the user would otherwise be one command away from root. As shipped, command-line Docker requires `sudo` (`sudo docker ps`, `sudo docker compose up`), while graphical tools that talk to the daemon — the [Lazydocker TUI](tuis-guis-and-browsers.md) on `Super + Shift + D` and the [Windows VM](apps-and-services.md) — request authorization when needed. Enabling **Setup > Security > Sudoless Docker** (or `omarchy-setup-security-sudoless-docker`) adds the user to the `docker` group after a warning, restoring plain `docker`/`d` alias use without `sudo` — a deliberate security tradeoff, not a default. Local development databases are available via _Install > Development > Docker DB_. ### GitHub CLI The GitHub CLI (`gh`) is another lazy-loading mise stub — it installs on first run. `gh auth login` authenticates; `gh repo clone org/repo` clones private repos once authenticated; running `gh` alone shows the full command surface. `ghui` is a lazy-installing stub for managing pull requests in a TUI, and [lazygit](https://github.com/jesseduffield/lazygit) is preinstalled for driving git itself from a TUI (see [[concepts/tuis-guis-and-browsers]]). ## Key Parameters - **Default agent** — set via `omarchy default agent ` or _Setup > Defaults > Agent_; drives `Super + Shift + Ctrl + A` and the `a` terminal shortcut. - **`docker` group membership** — off by default (security boundary); toggled on via Sudoless Docker setup. - **Mise** — the version manager underlying both the AI-agent launcher stubs and most language/runtime environments. - **Agent usage refresh interval** — 15 minutes (`omarchy agent usage-update`). - **Skill locations** — `~/.claude/skills`, `~/.codex/skills`, `~/.pi/agent/skills`, `~/.gemini/config/skills`, `~/.agents/skills`. ## When To Use - Setting up a coding environment from scratch — pick a default agent, install a language toolchain via mise, and decide the editor. - Delegating repetitive system customization (theming, Hyprland config, bar tweaks) to an agent via the Omarchy Skill, in plan mode first. - Choosing between sudo-gated Docker (safer default) and sudoless Docker (convenience) based on how much you trust what runs as your user. - Diagnosing a crash by handing a core dump straight to an agent instead of reading it manually. ## Risks & Pitfalls - Agents launched via the default-agent hotkey/CLI run **unattended and auto-approving** — they will act, not just suggest, once launched. - Agents won't accept trust for `$HOME`, so a launch from the home directory silently redirects to `~/Work` — a workflow expecting to operate on home-directory files there will not do what's expected. - Enabling **sudoless Docker** removes a real security boundary — the `docker` group is equivalent to passwordless root; only enable it after understanding that tradeoff. - The **Omarchy Skill is experimental** and model-dependent; blindly letting an agent apply system changes it suggests can make a mess. The manual recommends plan mode first and keeping `omarchy reinstall configs` as an undo path. - The AUR (used as a fallback for editors/tools not otherwise packaged) is unvetted — see [[concepts/apps-and-services]] for that tradeoff in more general package-installation context. ## Related Concepts - [[concepts/omarchy-cli-and-shell]] — the mise-managed lazy-stub pattern (`omarchy-mise-install`) and `omarchy update`/`mup` - [[concepts/terminal-and-neovim]] — the default editor and the `tdl`/`tsl` dev layouts that launch these same agents - [[concepts/tuis-guis-and-browsers]] — Lazydocker, Lazygit, and `ghui` as terminal interfaces to Docker/git/GitHub - [[concepts/theming]] — how theme changes propagate to Claude Code, Pi, and OpenCode - [[concepts/security]] — the `docker` group / sudoless Docker tradeoff in the broader security model - [[concepts/system-management]] — `omarchy reinstall configs` as a rollback path ## Sources - raw/github_doc-manual-17-ai-md.md - raw/github_doc-manual-18-development-tools-md.md - raw/github_release-v4-0-0.md --- title: "Apps and Services" type: concept tags: [apps, install, security, system] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-manual-24-commercial-apps-services-md.md", "raw/github_doc-manual-26-gaming-md.md", "raw/github_doc-manual-27-filling-out-pdfs-md.md", "raw/github_doc-manual-28-windows-vm-md.md", "raw/github_doc-manual-29-other-packages-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- ## Definition Beyond its open-source core, Omarchy provides easy installers for commercial software and services, a full gaming stack, PDF form-filling and signing, a Windows compatibility path via a virtual machine, and direct access to the whole Arch package ecosystem (official repo + AUR). All of it installs and removes through the same Omarchy menu pattern (_Install > X_ / _Remove > X_), whether the target is a password manager, a game store, or an arbitrary Arch package. ## How It Works ### Commercial apps and services Omarchy isn't ideologically opposed to commercial software — it just defaults to open source and offers commercial options as first-class alternatives where they're the better fit: | Service | What it is | Setup | |---------|-----------|-------| | [1Password](https://1password.com/) | Password manager with CLI key-lookup integration | `Super + Shift + /` (installs on first press if missing) or _Install > Service > 1Password_; also sets up the Chromium extension | | [Bitwarden](https://bitwarden.com/) | Open-source password manager, free tier for most personal use | _Install > Service > Bitwarden_ (brings its CLI too) | | [Spotify](https://spotify.com/) | Music streaming, including offline play | `Super + Shift + M` (installs on first press) or _Install > Service > Spotify_ | | [Dropbox](https://www.dropbox.com/) | Cross-machine file sync + cloud backup | _Install > Service > Dropbox_; finish setup by right-clicking its tray icon | | [Tailscale](https://tailscale.com/) | Mesh VPN for secure access across your machines | _Install > Service > Tailscale_; adds a bar panel, an admin-console web app, and Taildrop for file transfer between machines | | [ONCE](https://once.com/) | 37signals' buy-once, self-hosted software line (e.g. Campfire) | _Install > Service > ONCE_ — enables its background service and drops you into the ONCE terminal interface | | [NordVPN](https://nordvpn.com/) | General-purpose VPN, exit traffic from many regions | _Install > Service > NordVPN_ — requires a reboot, then `nordvpn login` to authenticate | ### Gaming All gaming installers live under _Install > Gaming_ (reversible via _Remove > Gaming_). Valve's [Proton](https://en.wikipedia.org/wiki/Proton_(software)) compatibility layer is what makes tens of thousands of Windows games playable on Linux at all (notably, the Steam Deck itself runs Arch). - **[Steam](https://store.steampowered.com/)** — native install; can take 10–20 seconds to launch with no visual loading feedback. - **[RetroArch](https://www.retroarch.com/)** — ships with the full set of libretro cores and the CRT Royale shader preconfigured. Drop BIOS files into `~/Games/bios` and ROMs into `~/Games/roms`, launch it (type `retro` after `Super + Space`), then scan the ROMs directory. _Install > Gaming > RetroArch Game Launcher_ gives an individual game its own app-launcher entry with a chosen core and ROM. - **Xbox Cloud Gaming** — installed as a web app; runs well at 1080p, a good option for Xbox Game Pass titles that don't run natively. - **[NVIDIA GeForce NOW](https://www.nvidia.com/en-us/geforce-now/)** — cloud gaming, same rationale as Xbox Cloud Gaming. - **Minecraft** — native install; like Steam, can be slow to progress screens with no feedback. - **Xbox Controllers** — Bluetooth controller support; pair via `Super + Ctrl + B` after installing. Not needed for USB-C wired controllers. - **[Moonlight](https://github.com/moonlight-stream/moonlight-qt)** — preinstalled game-streaming client for a Windows PC running [Sunshine](https://app.lizardbyte.dev/Sunshine/); launch via app launcher. On a hardwired LAN at native resolution/120Hz/max bitrate, it's indistinguishable from local play — a genuine option for competitive shooters. `omarchy install service sunshine` turns the Omarchy machine itself into the streaming host, opening the Moonlight ports for LAN and Tailscale. - **[Battle.net](https://eu.shop.battle.net/en-us)** — standalone install under GE-Proton (Diablo, StarCraft, WoW), no Steam/Lutris/Heroic needed. - **[Lutris](https://lutris.net/)** — for Windows games from stores without their own installer (EA, Ubisoft Connect); installs can look stalled while working in the background. - **[Heroic Launcher](https://heroicgameslauncher.com/)** — Epic Games titles without anti-cheat, plus GOG and Amazon Prime Gaming; notably **excludes Fortnite and Rocket League** (anti-cheat dependent) until Epic supports Linux natively. ### Filling out PDFs **Document Viewer** is the default PDF app (what double-clicking a PDF opens), but it can only fill in PDFs that were already set up as fillable forms. For any other PDF — or to sign one — right-click the file, choose _Open With..._, and pick **Xournal++**: use its `T` (text) tool to write anywhere on the page, and its Image tool to insert and resize a signature image. _File > Export as PDF_ saves the final, flattened result. ### Windows VM Omarchy runs Windows through a Docker-based VM ([Dockur](https://github.com/dockur/windows)), installed via _Install > Windows_. This needs KVM virtualization (usually available but sometimes disabled in BIOS — the installer detects and reports this) and disk space equal to whatever's allocated to Windows plus roughly 10GB for the image itself. The installer prompts for RAM, CPU cores, disk size (64GB+ recommended floor), and a Windows username/password — leaving those blank defaults to `docker`/`admin`. First download takes roughly 10–15 minutes, trackable in a browser at `http://127.0.0.1:8006`. Once installed, launching _Windows_ from the app launcher starts the VM (if needed) and connects over RDP, full screen, with a 15–30 second cold-start delay. The RDP session carries audio, microphone, and a shared clipboard between Linux and Windows, and the resolution/scaling follow the window so HiDPI displays aren't blurry. Closing the RDP window shuts the VM down automatically; `omarchy windows vm launch --keep-alive` leaves it running instead. Other controls: ```bash omarchy windows vm status # is it running? omarchy windows vm stop # shut it down omarchy windows vm launch # start and connect ``` `~/Windows` in the home directory is automatically shared with the VM — that's the *only* part of the filesystem the VM can reach, and its own virtual disk lives separately at `~/.windows`. All VM ports are bound to localhost only, so nothing on the local network can reach the Windows machine. There's no GPU passthrough, so the VM isn't suited to gaming or video editing — it's meant for things like Microsoft Office. The installed OS is Windows 11 Pro, unactivated; a real license key is required for gated features. If the host machine originally shipped with Windows, its OEM key is still in firmware and printable with `omarchy windows key`, though that key is bound to the physical hardware and usually will **not** activate the VM. Re-running `omarchy-windows-vm install` rewrites the VM's resource configuration from fresh answers. The VM's compose file lives at `/var/lib/omarchy/windows/docker-compose.yml`, **owned by root** — a deliberate choice so that a process running as the normal user can't rewrite it and have the privileged VM bring-up mount the whole disk into the container; hand-editing it (e.g. to mount a USB device) requires `sudo`. _Remove > Windows_ deletes the VM's disk and all its data — make sure anything worth keeping is moved out of the VM's own disk (`~/.windows`) and into `~/Windows` (or elsewhere) first, since `~/Windows` is the persistent host share and is not itself deleted. ### Other packages Arch's official repository plus the Arch User Repository (AUR) covers nearly any software category. _Install > Package_ (or `omarchy pkg add [package]` from the terminal) fuzzy-searches and installs from the official repo; _Install > AUR_ does the same against the AUR — which, unlike the official repo, isn't vetted by the Arch team (comparable to RubyGems or npm: anyone can upload). _Remove > Package_ (or `omarchy pkg drop [package]`) removes a package along with its config files and dependencies. ## Key Parameters - **KVM virtualization** — required for the Windows VM; must be enabled in BIOS if disabled. - **Windows VM disk floor** — 64GB+ recommended, plus ~10GB for the base image. - **VM network binding** — localhost only; VM filesystem access limited to `~/Windows`. - **`docker-compose.yml` ownership** — root, to prevent user-level rewrite of privileged VM bring-up. - **AUR trust model** — unvetted, upload-anyone (same class of risk as npm/RubyGems). ## When To Use - Reach for the Windows VM specifically for Windows-only productivity software (Office, niche Windows utilities) — not gaming or GPU-bound work, since there's no passthrough. - Use Moonlight + Sunshine (client/host streaming) instead of the VM when the goal actually is gaming with Windows-only titles or hardware-accelerated workloads. - Use Xournal++ instead of Document Viewer whenever a PDF isn't a real form or needs a signature. - Check _Install > Package_ before _Install > AUR_ — prefer the vetted official repo when the software exists there. ## Risks & Pitfalls - **Steam, Minecraft, Lutris, and Heroic all give little or no loading feedback** — a 10–20 second Steam startup or a stalled-looking Lutris install is often just working, not broken. - **The AUR is unvetted** — treat AUR packages with the same caution as an unfamiliar npm/RubyGems package; anyone can publish there. - **The Windows VM has no GPU passthrough** — don't plan on it for gaming or GPU video work. - **The host's firmware OEM Windows key usually won't activate the VM**, even though it's technically present and printable — a real license is still needed for VM activation. - **Removing the Windows VM deletes all of its data**, including anything left only inside the VM's own disk (not `~/Windows`) — back up first. - Heroic Launcher **cannot run Fortnite or Rocket League** (anti-cheat dependent) — don't expect those titles until Epic supports Linux natively. ## Related Concepts - [[concepts/security]] — root ownership of the VM compose file, localhost-only VM networking, and the AUR trust boundary - [[concepts/ai-and-dev-tools]] — Docker's sudo-by-default posture, which the Windows VM's own graphical prompt mirrors - [[concepts/tuis-guis-and-browsers]] — Moonlight and the app-launcher pattern shared with gaming/service installs - [[concepts/system-management]] — `omarchy pkg add`/`omarchy pkg drop` as the general package-management surface ## Sources - raw/github_doc-manual-24-commercial-apps-services-md.md - raw/github_doc-manual-26-gaming-md.md - raw/github_doc-manual-27-filling-out-pdfs-md.md - raw/github_doc-manual-28-windows-vm-md.md - raw/github_doc-manual-29-other-packages-md.md - raw/github_release-v4-0-0.md --- title: "Coming From Mac or Windows" type: concept tags: [overview, navigation, foundational, well-established, user] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-manual-03-coming-from-mac-or-windows-md.md", "raw/github_release-v4-0-0.md"] confidence: high omarchy_version: "v4.0.0" --- # Coming From Mac or Windows ## Definition "Coming From Mac or Windows" is Omarchy's translation layer for users whose muscle memory comes from macOS or Windows. Rather than re-teaching the underlying features (covered elsewhere in the manual), it maps familiar habits and keyboard reflexes onto their Omarchy equivalents, centered on one idea: nearly every instinct built around Cmd (Mac) or the Windows key transfers to a single key in Omarchy — **Super**. ## How It Works - **Super is the hub.** The Spotlight/Raycast/Start-menu reflex becomes `Super + Space`, which opens the [[concepts/the-menu|Omarchy menu]] — launching apps, changing settings, installing software, capturing the screen, and more, with type-to-filter search. A dedicated apps-only menu is `Super + Alt + Space`. - **No dock, no desktop icons.** There is nothing to click to launch apps. Apps start via hotkey (`Super + Return` terminal, `Super + Shift + Return` browser, `Super + K` to list every mapped hotkey) or via the menu. The one persistent piece of UI is the top bar (see [[concepts/navigation-and-hotkeys]]), which replaces the menu bar, system tray, and Notification Center — nearly every widget on it responds to left, right, and middle click. - **Windows tile instead of overlapping.** The biggest mindset shift: windows are not dragged or snapped — a single open window takes the full screen, and a second automatically splits it. Windows never overlap, so there's no fishing a window out from behind another. `Super + T` toggles the active window out of tiling into a floating state (and back) when floating is genuinely needed. Workspaces work like macOS Spaces or Windows virtual desktops, but jump instantly with no animation delay: `Super + 1/2/3/4` switches to a workspace, `Super + Shift + 1/2/3/4` sends the focused window there. - **Universal copy/paste.** `Super + C`, `Super + X`, and `Super + V` work everywhere, including inside the terminal — unlike the traditional Linux split of `Ctrl+Shift+C/V` in terminals vs. `Ctrl+C/V` elsewhere. Windows users' `Win + V` clipboard-history reflex becomes `Super + Ctrl + V`, which holds both images and text (see [[concepts/navigation-and-hotkeys]] for the full hotkey system). - **The translation table**, verbatim from the manual: | You reach for | In Omarchy | | ------------- | ---------- | | Spotlight / Raycast / Start menu | `Super + Space` — the Omarchy menu | | AirDrop | LocalSend, via `Super + Ctrl + S` | | Cmd + Shift + 4 / Win + Shift + S | `Print Screen` — screenshots & recording | | Notification Center | Notification history on `Super + Shift + Alt + ,` | | Time Machine (for the system) | Automatic system snapshots on every update | | App Store / downloading an installer | _Install_ in the menu, or `omarchy pkg add` | | System Settings / Control Panel | _Setup_ in the menu, which edits plain config files | - **Real differences, not just remapped keys.** Settings live in plain text config files edited directly rather than clicked through in panels — the trade-off is that every tweak is visible, copyable to another machine, and version-controllable. The _Setup_ menu opens the right file directly and restarts whatever needs restarting. System-wide updates come through a single _Update > Omarchy_ command that updates Omarchy and every package at once (taking a snapshot first), replacing per-app auto-updaters. Software installs via a package manager, not downloaded installers. Closing a window actually quits the app — there is no macOS-style "still running with no windows" limbo; `Super + W` or `Super + Q` means the app is gone. - **On Mac hardware specifically**, Omarchy runs well on Intel Macs (see [[concepts/installation]]) and does not remap the keyboard — Linux treats the Command key as Super, so Super sits exactly where Cmd always was. ## Key Parameters - **Super** — the single anchor key for almost all hotkeys, replacing both Cmd and the Windows key. - **`Super + Space`** — opens the full Omarchy menu (Spotlight/Start-menu equivalent). - **`Super + K`** — shows every keyboard binding; described as "the only hotkey you actually have to memorize." - Adjustment period: the manual suggests giving the new model "two weeks" before judging it. ## When To Use Read this chapter first, before diving into [[concepts/navigation-and-hotkeys]] or [[concepts/the-menu]], if arriving from macOS or Windows — it front-loads the conceptual remapping (tiling instead of floating windows, menu instead of Start/Spotlight, config files instead of settings panels) so the rest of the manual's specifics make sense in context. ## Risks & Pitfalls - Users who fight the tiling model instead of giving it "a real chance" will find Omarchy frustrating — the manual is explicit that tiling "is the heart of the whole thing." - Expecting a dock, desktop icons, or drag-to-snap window management will lead to confusion; none of these exist by default. - Windows users may initially miss per-app updaters or an installer-based software flow; Omarchy replaces both with a single system-wide update command and a package manager. - Assuming closed apps keep running in the background (as on macOS) is incorrect — closing the window quits the app. ## Related Concepts - [[concepts/omarchy-overview]] — the broader philosophy behind these differences - [[concepts/navigation-and-hotkeys]] — full hotkey reference and tiling mechanics - [[concepts/the-menu]] — the unified menu referenced throughout this translation - [[concepts/installation]] — Mac hardware support details ## Sources - raw/github_doc-manual-03-coming-from-mac-or-windows-md.md - raw/github_release-v4-0-0.md --- title: "Hyprland and Window Management" type: concept tags: [hyprland, navigation, foundational, user, well-established] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-default-agents-skills-omarchy-hyprland-md.md", "raw/github_doc-manual-04-navigation-md.md", "raw/github_doc-manual-33-monitors-md.md", "raw/github_doc-manual-31-dotfiles-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- # Hyprland and Window Management ## Definition [Hyprland](https://wiki.hypr.land/) is the tiling Wayland compositor that does the actual window-management work underneath Omarchy — the window tiling, workspace, and keyboard-focus behavior described in [[concepts/omarchy-overview]] and [[concepts/navigation-and-hotkeys]] is Hyprland's doing. Omarchy configures Hyprland almost entirely through a set of Lua files under `~/.config/hypr/`, which sit on top of Omarchy's own shipped defaults. As of v4.0.0 ("Quattro"), all Hyprland configuration was converted from the historical `.conf`/hyprlang syntax to Lua for compatibility with Hyprland 0.56 (see [[summaries/release-digest]]). ## How It Works User overrides to Omarchy's Hyprland configuration go under `~/.config/hypr/`, loaded after Omarchy's own shipped defaults: ``` ~/.config/hypr/ ├── hyprland.lua # Main config (loads Omarchy defaults, then user files) ├── bindings.lua # Keybindings ├── monitors.lua # Display configuration ├── input.lua # Keyboard/mouse settings ├── looknfeel.lua # Appearance (gaps, borders, animations) ├── autostart.lua # Startup applications ├── hyprsunset.conf # Night light / blue light filter └── xdph.conf # Screen sharing / desktop portal ``` Hyprland auto-reloads its Lua config on save for most changes; `hyprctl reload` forces a reload, and `hyprctl configerrors` validates it. The two `.conf` files are read by separate processes and are not touched by `hyprctl`: `hyprsunset.conf` needs `omarchy restart hyprsunset` to apply, and `xdph.conf` (screen-sharing portal) applies on the portal's next restart (e.g., next login). `omarchy refresh hyprland` resets the Lua files back to Omarchy's defaults — a Hyprland-specific reset, distinct from the generic dotfile-reset routes (`_Update > Config_` or `omarchy reinstall configs`) described in [[concepts/system-management]]. **Keybindings** are edited in `bindings.lua` with Omarchy's own binding helper: ```lua o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server") o.bind("SUPER + B", "Browser", { launch = "chromium" }) -- launch wraps with uwsm-app ``` `omarchy menu keybindings --print` lists current bindings. Rebinding a key that's already bound requires calling `hl.unbind(...)` first (e.g., `hl.unbind("SUPER + F")` before rebinding `SUPER + F`, which defaults to fullscreen), otherwise the two bindings collide. **Monitors** are configured in `monitors.lua` with `hl.monitor` entries: ```lua hl.monitor({ output = "eDP-1", mode = "1920x1080@60", position = "0x0", scale = 1 }) hl.monitor({ output = "HDMI-A-1", mode = "2560x1440@144", position = "1920x0", scale = 1 }) ``` `hyprctl monitors all` lists connected monitors and their supported modes. Workspace-to-monitor pinning rules also live in `monitors.lua`, and Omarchy ships commented examples for pinning a monitor to a resolution, position, and rotation (see [[concepts/monitors-and-hardware]] for scaling and multi-screen setup specifics). **Window rules** are the one area the skill explicitly warns is version-fragile: Hyprland's window-rule syntax changes frequently, so the current syntax must be fetched from the official Hyprland wiki (`https://wiki.hypr.land/Configuring/Basics/Window-Rules/`) rather than relied on from memory. Omarchy's `o.window(match, rules)` helper (examples in `$OMARCHY_PATH/default/hypr/windows.lua`) is the preferred way to add rules, placed in `hyprland.lua` or a required Lua module. ### Navigation model Omarchy is designed to be fully keyboard-operable — on first boot, nothing can be done with the mouse alone until `Super + Space` opens the Omarchy menu (see [[concepts/the-menu]]). The most-used apps are bound directly to hotkeys: `Super + Return` opens a terminal, `Super + Shift + Return` a browser. Opening both in sequence demonstrates tiling directly: the two windows split the screen automatically. `Super + J` stacks/unstacks windows, `Super + Shift + Arrow` swaps window positions, and `Super + Arrow` moves keyboard focus (and the cursor) between windows. `Super + Shift + ` sends the focused window to workspace `n`; adding `Alt` sends it there without switching workspaces. Holding `Super` and dragging with the mouse repositions a window; holding `Super` and dragging with the right mouse button resizes it. Windows close with `Super + W` or `Super + Q` (or `Ctrl + Alt + Delete` for all windows at once). Fullscreen is `Super + F`; full-width-but-keep-bar is `Super + Alt + F`; fullscreen-within-a-window is `Super + Ctrl + F`. ### Layouts: dwindle vs. scrolling Omarchy's default tiling layout is **dwindle**, which keeps every window on a workspace visible at once, shrinking them as needed. `Super + L` toggles a single workspace into the **scrolling** layout instead, where windows line up side-by-side beyond the visible screen edge. The choice is per-workspace and persists across restarts, so (for example) workspace 1 can stay on dwindle for browsing while workspace 2 uses scrolling for code. Setting scrolling as the system-wide default is done in `looknfeel.lua`: ```lua hl.config({ general = { layout = "scrolling", }, }) ``` ### Grouping, popping, and the scratchpad - **Grouping** (`Super + G`) bundles windows into a tabbed set; new windows opened while a group is active join it. `Super + Ctrl + Arrow Left/Right` or `Super + Alt + 1/2/3/4` move between grouped windows; `Super + Alt + G` removes one window from the group, and `Super + G` again disbands it. - **Popping** (`Super + O`) pins a window as a floating window that follows across workspaces — good for video players. - **Scratchpad** is a Quake-console-style drop-down workspace toggled with `Super + Grave`/`Super + S`, with `Super + Shift + Grave`/`Super + Alt + S` sending a window there. It's well suited to a terminal running a coding agent (see [[concepts/ai-and-dev-tools]]) or quick controls, without leaving the current workspace. ## Key Parameters - **Config language**: Lua, loaded from `~/.config/hypr/*.lua` (as of v4.0.0/Quattro; earlier versions used hyprlang `.conf` syntax). - **Default layout**: dwindle; alternative: scrolling (`Super + L`, per-workspace, persistent). - **Reload commands**: `hyprctl reload` (apply), `hyprctl configerrors` (validate), `omarchy refresh hyprland` (reset Lua files to Omarchy defaults). - **Non-hyprctl configs**: `hyprsunset.conf` (`omarchy restart hyprsunset`), `xdph.conf` (applies on portal restart). - **Binding helper**: `o.bind(keys, label, action)`; unbinding via `hl.unbind(keys)`. - **Monitor helper**: `hl.monitor({ output, mode, position, scale, ... })`. ## When To Use Read the Hyprland skill/config model before changing any keybinding, monitor layout, window rule, or general Hyprland behavior — it is the mechanism behind essentially all window-management customization in Omarchy. The navigation model (dwindle/scrolling, grouping, popping, scratchpad) is relevant whenever a user is deciding how to organize screen real estate for a given workflow, e.g., a wide monitor for scrolling-layout code columns, or a scratchpad terminal for an always-available agent session. ## Risks & Pitfalls - **Window-rule syntax drifts across Hyprland versions.** Never rely on memorized or cached window-rule syntax — always check the live Hyprland wiki page before writing rules, since outdated syntax causes errors or unexpected behavior. - **Rebinding an already-bound key silently conflicts** unless the old binding is explicitly unbound first with `hl.unbind(...)`; the skill's convention is to always unbind before rebinding and tell the user what was previously on that key. - **Editing files outside `~/.config/hypr/` is a dead end** — anything under `/usr/share/omarchy` belongs to the Omarchy package and is overwritten on update (see [[concepts/system-management]]). - The `.conf`-based hooks (`hyprsunset.conf`, `xdph.conf`) don't validate or apply through `hyprctl`, so a change there can silently not take effect until the relevant process is restarted. - The v4.0.0 Lua conversion means any documentation, community configs, or muscle memory from pre-Quattro (hyprlang `.conf`) Omarchy installs needs updating (see [[summaries/release-digest]]). ## Related Concepts - [[concepts/omarchy-overview]] — Hyprland's place in the three-layer Omarchy stack - [[concepts/navigation-and-hotkeys]] — the broader hotkey system beyond window management - [[concepts/the-menu]] — the Quickshell menu used to reach `Setup > Monitors`, `Setup > Keybindings`, etc. - [[concepts/monitors-and-hardware]] — monitor scaling, multi-screen arrangement, and brightness - [[concepts/system-management]] — dotfiles, resets, and how config changes survive updates - [[summaries/release-digest]] — the v4.0.0 Lua config conversion and shell rewrite ## Sources - raw/github_doc-default-agents-skills-omarchy-hyprland-md.md - raw/github_doc-manual-04-navigation-md.md - raw/github_doc-manual-33-monitors-md.md - raw/github_doc-manual-31-dotfiles-md.md - raw/github_release-v4-0-0.md --- title: "Installation" type: concept tags: [install, foundational, well-established, user] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-manual-02-getting-started-md.md", "raw/github_doc-manual-50-dual-boot-install-md.md", "raw/github_doc-manual-51-unattended-installs-md.md", "raw/github_doc-manual-44-mac-support-md.md", "raw/github_doc-manual-49-omarchy-on-md.md", "raw/github_doc-manual-06-themes-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- # Installation ## Definition Omarchy is installed from a bootable ISO downloaded from omarchy.org. The installer supports several paths: a full-disk install that wipes and takes over an entire drive, a free-space (dual-boot) install into unallocated space alongside an existing OS, an unattended/scripted install for VMs and fleet machines, built-in support for Intel Mac hardware, and community-contributed paths for Apple Silicon Macs and various virtual machines. ## How It Works **Standard install.** Download the Omarchy ISO, write it to a USB stick (balenaEtcher on Mac/Windows, [caligula](https://github.com/ifd3f/caligula) on Linux), and boot from it. Secure Boot and/or TPM must be disabled in the BIOS first — these are described as "Microsoft security schemes meant for Windows and Microsoft-affiliated Linux distributions" and installation cannot proceed with them on. The installer then asks configuration questions, lets you pick a drive, and runs — typically under a minute on fast hardware, rarely more than 5 minutes on older machines. Installation defaults to **full disk encryption**, and the full-disk option **wipes the selected drive**, so backups are essential beforehand. A wired or 2.4GHz-dongle keyboard is needed to enter the full-disk-encryption password at boot: a Bluetooth keyboard can't type that password at startup (the same limitation as entering a PC BIOS over Bluetooth). **Installing for another owner.** Hitting `Ctrl + C` on the very first installer screen (keyboard selection) switches to a mode that defers all personal setup — keyboard layout, username, password — to the machine's first boot, so the person setting up the machine (e.g., for a family member or new employee) never has to answer personal questions on their behalf. The drive is still encrypted by default; the password chosen on first boot becomes the encryption password. **No-encryption installs.** Because encryption is the default, hitting `Ctrl + C` on the disk-formatting confirmation screen switches to an unencrypted install — intended only for special cases like remote installs on protected computers or throwaway installs with no sensitive data. **Dual-boot / free-space install** (see [[concepts/omarchy-overview]] for the base system): to make room alongside Windows, use Windows' Disk Management to shrink the target volume (`disk management` → **Create and format hard disk partitions** → right-click the partition → **Shrink Volume**), sized to cover the full future Omarchy install including its boot partition. During the Omarchy installer, after selecting the disk, choose **Free space install** instead of a full-disk wipe. This mode still applies LUKS encryption to the partition by default, so it behaves like a full-disk install except that it only needs free space rather than the whole disk. **BitLocker must be turned off first** (Windows Settings → Privacy & Security → Device encryption) — dual-boot install is incompatible with BitLocker because BitLocker encrypts the entire drive rather than just a partition. After install, the Limine bootloader is installed by default; running `limine-scan` adds other detected OS installs (e.g., Windows Boot Manager) to the boot menu. **Unattended installs.** The ISO can install itself with nobody at the keyboard: if it finds a second drive labeled `cidata` (the cloud-init `NoCloud` label) carrying configuration files, it copies them off, skips the setup wizard entirely, and reboots into the finished system. With no such drive attached, the normal interactive wizard runs unchanged. This makes Omarchy suitable as a base image for disposable VMs (Proxmox, Packer, etc.). Required files on the `cidata` drive: | File | Required | Purpose | |------|----------|---------| | `user_configuration.json` | Yes | Disk, hostname, timezone, keyboard | | `user_credentials.json` | Yes | Username and password hash | | `user_full_name.txt` | No | Git full name | | `user_email_address.txt` | No | Git email | | `user_encrypt_installation.txt` | No | `true` when the configuration carries a `disk_encryption` block | | `authorized_keys` | No | SSH public keys, one per line | | `tailscale_authkey` | No | Tailscale auth key to join a tailnet on first boot | The easiest way to produce these files is to run one interactive install (e.g. in a VM) and copy what it wrote out of `/root`. The password hash for `user_credentials.json` is generated with `openssl passwd -6 "yourpassword"`. Dropping an empty file named `defer-provisioning` in place of `user_credentials.json` triggers the same "prepare for another owner" flow as the interactive `Ctrl+C` path — no personal details are baked in, and whoever boots the machine first sets up their own account. If `authorized_keys` is present, the installer enables `sshd`, opens the firewall for it, and installs the keys — normally SSH is shipped disabled and closed. If `tailscale_authkey` is present, Tailscale is installed and joins the tailnet on first boot via a retrying background job (use a reusable, pre-authorized key so one image can provision many machines). A minimal `cidata` drive can be built as an ISO: ```bash mkdir cidata cp user_configuration.json user_credentials.json authorized_keys cidata/ genisoimage -output cidata.iso -volid cidata -joliet -rock cidata/ ``` A full Proxmox example attaches both the Omarchy ISO and the `cidata.iso` as CD-ROMs, with the empty target disk listed first in `--boot order` so it falls through to the installer ISO on first boot only. Two caveats: encrypted unattended installs still require someone to type the LUKS passphrase at first boot (they aren't fully hands-off), and the `disk_encryption` block in `user_configuration.json` carries that passphrase in plaintext — a `cidata` drive built from an encrypted install must be treated as a secret. **Mac support.** Omarchy has **built-in** support for **Intel Macs**; M-series (Apple Silicon) Macs are not directly supported (community efforts tracked in the `#omarchy-on-other` Discord channel). Installing on Mac wipes the drive — Omarchy must be the only OS, though macOS can later be restored via Internet Recovery. Installation requires disabling Apple's Secure Boot first (boot into Recovery with Command-R, then **Utilities → Startup Security Utility** → choose "No Security" and "Allow booting from external or removable media"), then booting the USB installer by holding Option at startup and selecting the orange EFI Boot device. The installer auto-detects Mac hardware and applies fixes: Broadcom Wi-Fi drivers/firmware, the SPI keyboard driver on MacBook models that need it, and an NVMe suspend fix. Known limitations: on **T1-chip** MacBook Pros (2016 Touch Bar models, A1706/A1708/A1707) the Touch Bar and sound don't work. On **T2-chip** Macs (2017–2020 models listed in the manual), the installer sets up the patched `linux-t2` kernel, T2 audio config, Apple's Broadcom Wi-Fi/Bluetooth firmware, and fan control via `t2fanrd`, with Touch Bar support via the kernel's Boot Camp-style driver. A simple test on a 2019 MacBook Pro reported a 36% performance gain from installing Omarchy; the source doesn't detail the exact baseline or benchmark used. **Other platforms ("Omarchy on...").** These are community-contributed guides and ports, distinct from the built-in Intel Mac support above: Apple M1/M2 via [Asahi Alarm](https://asahi-alarm.org/) (a user-driven guide exists); inside a Parallels VM; inside VirtualBox (performance "probably won't be great"); inside VMware Workstation on Windows 11; on Steam Deck via a community setup script; and a NixOS port ("essence of the setup," may lag the latest Omarchy release). Anything outside these is directed to the `#omarchy-on-other` Discord channel. ## Key Parameters - **Install modes**: full-disk (wipes drive) vs. free-space/dual-boot (needs unallocated space only). - **Encryption**: on by default (LUKS); `Ctrl+C` on the disk-format confirmation disables it. - **Deferred setup**: `Ctrl+C` on the first installer screen defers keyboard/username/password to first boot. - **Unattended trigger**: a second drive labeled `cidata` (cloud-init NoCloud label). - **Bootloader**: Limine by default; `limine-scan` adds other OS entries. - **Mac support scope**: Intel Macs only, officially; T1/T2-chip models have specific caveats. - **Keyboard requirement**: wired or 2.4GHz dongle keyboard needed to enter the full-disk-encryption password at boot (a Bluetooth keyboard can't do this). ## When To Use Use the standard full-disk install for a dedicated Omarchy machine. Use the dual-boot/free-space path when Windows (or another OS) must be preserved alongside Omarchy — after disabling BitLocker. Use unattended installs when provisioning VM base images or fleets of disposable dev machines where nobody is at the keyboard. Use the Mac-support path only on supported Intel Mac hardware, understanding it fully replaces macOS unless later restored via Internet Recovery. ## Risks & Pitfalls - Full-disk install **wipes the selected drive** — back up first. - Secure Boot/TPM must be disabled in BIOS or installation cannot proceed at all. - A Bluetooth-only keyboard cannot enter the LUKS passphrase at boot — use wired or 2.4GHz. - Dual-boot install is **not compatible with BitLocker**; it must be turned off in Windows first or the installer errors. - Unattended installs with encryption are not fully hands-off — someone must still type the LUKS passphrase at first boot. - A `cidata` drive built from an encrypted install stores the LUKS passphrase in **plaintext** in `user_configuration.json` — must be handled as a secret. - M-series (Apple Silicon) Macs are not directly supported; attempting it requires community (Asahi-based) workarounds outside the official manual. - On Mac hardware, installing wipes macOS — it can be restored afterward via Internet Recovery. - T1-chip Macs lose Touch Bar and sound functionality entirely; no fix is documented. ## Related Concepts - [[concepts/omarchy-overview]] — what you're installing and why it's opinionated - [[concepts/coming-from-mac-or-windows]] — post-install orientation for switchers - [[concepts/theming]] — encryption and boot-unlock screens can be themed after install ## Sources - raw/github_doc-manual-02-getting-started-md.md - raw/github_doc-manual-50-dual-boot-install-md.md - raw/github_doc-manual-51-unattended-installs-md.md - raw/github_doc-manual-44-mac-support-md.md - raw/github_doc-manual-49-omarchy-on-md.md - raw/github_doc-manual-06-themes-md.md - raw/github_release-v4-0-0.md --- title: "Monitors and Hardware" type: concept tags: [hyprland, system, hardware, foundational, user, well-established] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-manual-33-monitors-md.md", "raw/github_doc-manual-37-hardware-authentication-md.md", "raw/github_doc-docs-audio-tuning-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- # Monitors and Hardware ## Definition This page covers three adjacent pieces of physical-hardware configuration in Omarchy: monitor setup and scaling (resolution, DPI, multi-screen arrangement, brightness), hardware-backed authentication (fingerprint, Fido2), and per-laptop audio tuning (correcting internal-speaker frequency response). All three are hardware-specific layers on top of the general dotfiles/hooks model described in [[concepts/system-management]]. ## How It Works ### Monitor scaling Omarchy assumes a 2x-capable retina-class display by default (PPI ≥ 218, e.g., a 27" 5K or 32" 6K display) — the configuration that produces crisp programmer fonts out of the box. On a lower-DPI display, `~/.config/hypr/monitors.lua` (reachable via _Setup > Monitors_) needs adjustment: - **27"/32" 4K** displays should use fractional scaling: ```lua local omarchy_gdk_scale = 2 local omarchy_monitor_scale = 1.6 ``` - **1080p/1440p** displays should use 1x scaling: ```lua local omarchy_gdk_scale = 1 local omarchy_monitor_scale = 1 ``` `GDK_SCALE` changes apply only to newly started applications (GTK only honors whole numbers, so it's rounded to the nearest integer of the monitor scale) — already-open oversized windows need to be closed, or all windows closed at once with `Ctrl + Alt + Del`. `Super + /` (up) and `Super + Alt + /` (down) step through the major scaling ratios (1x, 1.25x, 1.6x, 2x, 3x, 4x) live, and with the default config these changes persist across reboot. **Text-only sizing**: `omarchy display text size 14` (accepts 9–20px) resizes the Omarchy shell, GTK apps, and terminal font together, keeping proportions consistent, without touching overall monitor scale. Running it with no argument shows the current size; `omarchy display text size reset` restores the default. Foot is the one exception — it has no config-reload mechanism, so already-open Foot terminals keep their old size until a new one is opened. ### Multi-monitor arrangement Connecting an external screen to a laptop extends the display automatically; _Trigger > Hardware_ (or `Super + Ctrl + Alt + Delete`) switches to mirroring instead — useful for projectors. While extending, closing the laptop lid automatically disables the internal screen, and opening it re-enables it; this can also be controlled manually via _Trigger > Hardware_ or `Super + Ctrl + Delete`. Detailed multi-screen layout rules follow [the Hyprland monitor documentation](https://wiki.hypr.land/Configuring/Basics/Monitors/) and [workspace-to-monitor binding rules](https://wiki.hypr.land/Configuring/Basics/Workspace-Rules/); in Omarchy these live as `hl.monitor` entries in `monitors.lua` (see [[concepts/hyprland-and-window-management]]), which ships with commented examples for pinning a monitor to a resolution, position, and rotation. [Hyprmon](https://github.com/erans/hyprmon/) is a third-party TUI for assisting multi-screen layout. ### Brightness and Apple displays Dedicated brightness function keys control the currently focused display; holding Shift jumps to maximum/minimum brightness. External monitors that support DDC/CI are adjusted the same way as the internal laptop screen. Apple displays additionally work with the regular keyboard brightness keys (via the `asdcontrol` command) when focused. A known quirk: an Apple 6K XDR display may show a phantom second screen in `hyprctl monitors` output, disabled with `hl.monitor({ output = "DP-2", disabled = true })` via _Setup > Monitors_. Intel machines should connect to Apple displays over a regular Thunderbolt cable; non-Thunderbolt machines typically need a DP + USB-A → USB-C cable. ### Hardware authentication **Fingerprint**: _Setup > Security > Fingerprint_ in the Omarchy menu installs the fingerprint package, collects and verifies a print, and enables it for unlocking the lock screen (`Super + Ctrl + L`), entering sudo mode, and authorizing system prompts. When the laptop lid is closed, the fingerprint prompt is automatically skipped in favor of the password prompt (since the sensor can't be reached). Working on an external keyboard without a sensor: hit `Ctrl + C` at the fingerprint prompt during `sudo` to fall through to a password. Removed via _Remove > Security > Fingerprint_. **Fido2**: _Setup > Security > Fido2_ sets up a Fido2 device for `sudo` and system-authorization prompts only — it does not cover unlocking the computer. Removed via _Remove > Security > Fido2_. ### Speaker tunings (audio hardware correction) Laptop speakers are voiced by the vendor's Windows DSP layer, which Linux doesn't provide by default. Omarchy restores that voicing as a PipeWire filter-chain in front of the internal speaker sink — a declarative graph with no GUI and no binary blob, per-vendor-model directory: ``` default/audio/tunings/-/ ├── tuning.conf # description, match, provenance, measurements └── filter-chain.conf # the graph, with @SPEAKER_SINK@ substituted on install ``` Turning a tuning `on` renders the graph into `~/.config/pipewire/omarchy-speaker-tuning.conf.d/` and runs it as its own PipeWire client (`omarchy-speaker-tuning.service`) rather than loading it into the audio daemon directly — this way switching a tuning is just a start/stop of one small process, and a malformed tuning only breaks that service rather than blocking PipeWire from starting at all. Tunings apply automatically on matching hardware at first-run; machines without a matching tuning are untouched. ```bash omarchy audio tuning on # install the matching tuning omarchy audio tuning off # remove it, back to raw speakers omarchy audio tuning status # installed? in use? what matches? ``` Matching is data-driven via `tuning.conf` keys, checked in this priority order — only the first *defined* key is consulted: `match_command` (a custom predicate) > `match_sku` (DMI product SKU — most precise, since vendors key speaker firmware on it) > `match_dmi` (DMI product/family name substring — convenient but widens fast). Both `match_sku` and `match_dmi` accept lists, letting one tuning cover several validated models, e.g. `match_sku=("0DB9" "0DBA")` for XPS 14 and XPS 16. Two hard authoring requirements: a tuning **must end in a limiter** (peaks under 0 dBFS with headroom), and must **not boost frequencies the drivers can't deliver** — the shipped XPS 14 tuning deliberately cuts 40 Hz by ~18 dB rather than trying to reproduce it. A tuning also declares its `sink_pattern` (the sink its graph targets) and must keep two fixed graph properties: the output sink node named exactly `omarchy_speaker_tuning`, and its output stream setting `node.dont-fallback`/`node.dont-move` so WirePlumber can't relink it elsewhere. Measuring and building a new tuning is a separate, non-default tool, [omarchy-audio-tuner](https://github.com/omacom-io/omarchy-audio-tuner) (`omarchy pkg add omarchy-audio-tuner`), which requires Python, ffmpeg, and mpv, and supports both copying a known-good reference (no microphone needed) and measuring from scratch with a calibrated mic. A tuning submission is expected to report measured `magnitude_rms_db`, `bass_group_delay_swing_ms`, `limiter_headroom_db`, and `dynamic_range_delta_lu` in `tuning.conf`. Two system interactions worth knowing: **EasyEffects cannot coexist with a tuning** (`on` refuses to install while it's running, since EasyEffects would grab the stream back), and **volume always resolves through the physical sink**, not the tuning's virtual sink, via `omarchy-audio-output-sink` — so changing volume doesn't distort the tuning's processing, and the physical/raw speaker sink that the tuning fronts is deliberately hidden from the output picker (reported unavailable, skipped by the output switcher) so users can't bypass the tuning by selecting the raw speakers directly. ## Key Parameters - **Retina-display threshold**: PPI ≥ 218 assumed by default (`omarchy_gdk_scale`/`omarchy_monitor_scale` = gdk_scale 2 / monitor_scale 1.6 on 27"/32" 4K vs. 1x/1x for 1080p/1440p). - **Scaling step cycle**: 1x, 1.25x, 1.6x, 2x, 3x, 4x via `Super + /` / `Super + Alt + /`. - **Text size range**: 9–20px via `omarchy display text size `. - **Speaker tuning match priority**: `match_command` > `match_sku` > `match_dmi`. - **Speaker tuning requirements**: ends in a limiter; never boosts frequencies the driver can't deliver. - **Fingerprint scope**: lock screen, sudo, system prompts. **Fido2 scope**: sudo and system prompts only (not lock-screen unlock). ## When To Use Reach for this page when a display looks blurry or oversized (DPI/scaling mismatch), when arranging or troubleshooting multiple monitors, when setting up biometric or hardware-key login/sudo, or when a laptop's built-in speakers sound thin, boomy, or otherwise "off" and a vendor-specific tuning might apply. ## Risks & Pitfalls - **`GDK_SCALE` changes don't retroactively resize already-open windows** — quitting and reopening (or `Ctrl + Alt + Del`) is required, which can be surprising mid-session. - **Foot terminals don't live-reload their font size** — a stale terminal keeps the old size until a fresh one is opened, even after `omarchy display text size` is changed. - **A tuning aimed at the wrong hardware can sound worse than none**, and can stress drivers not designed for the corrected curve — gating should stay narrow (`match_sku`) and widen deliberately as more models are validated, with any un-measured coverage documented rather than implied. - **Fido2 does not cover screen unlock**, only `sudo`/system prompts — a common expectation mismatch with fingerprint auth, which does cover unlock. - **EasyEffects and a speaker tuning are mutually exclusive**; installing a tuning while EasyEffects runs is refused rather than silently producing a bypassed graph. - Apple 6K XDR displays can show a phantom monitor entry that needs manual disabling, and DDC/CI brightness support on external monitors is hardware-dependent. ## Related Concepts - [[concepts/hyprland-and-window-management]] — `monitors.lua` and `hl.monitor` mechanics that scaling and multi-screen setup build on - [[concepts/system-management]] — the general dotfiles/hooks model these hardware configs live inside - [[concepts/security]] — how fingerprint/Fido2 auth relates to sudo and drive-encryption passwords - [[concepts/tweaks-troubleshooting-and-faq]] — recovering when Wi-Fi/Bluetooth/audio/trackpad misbehave after hardware changes ## Sources - raw/github_doc-manual-33-monitors-md.md - raw/github_doc-manual-37-hardware-authentication-md.md - raw/github_doc-docs-audio-tuning-md.md - raw/github_release-v4-0-0.md --- title: "Navigation and Hotkeys" type: concept tags: [navigation, foundational, well-established, user, power-user] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-manual-04-navigation-md.md", "raw/github_doc-manual-05-the-top-bar-md.md", "raw/github_doc-manual-07-hotkeys-md.md", "raw/github_doc-manual-34-keyboard-mouse-trackpad-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- # Navigation and Hotkeys ## Definition Navigation in Omarchy is entirely keyboard-driven: at first boot "you literally can't do a thing with the mouse alone." The system combines Hyprland's automatic tiling window management, a persistent top bar drawn by the Quickshell-based Omarchy shell, and a very large hotkey surface (most primary bindings anchored on the **Super** key, with brightness/volume adjustment, media control, and some capture bindings instead using Shift, Alt, Print Screen, or function keys) into one coherent way of operating the desktop. Input devices (keyboard layout, mouse/trackpad behavior) are configured separately through Hyprland's Lua config. ## How It Works ### Tiling and window movement `Super + Space` reveals the [[concepts/the-menu|Omarchy menu]], from which almost anything can be done, but it is not meant to be the primary way of working — direct hotkeys are faster. `Super + Return` opens a terminal and `Super + Shift + Return` a browser; opening one after another demonstrates Hyprland tiling automatically splitting the screen. `Super + J` stacks the two windows on top of each other instead of side by side (press again to restore side-by-side), and `Super + Shift + Arrow Right` (while a window is focused) swaps it with its neighbor. `Super + Ctrl + T` starts the Activity monitor (btop) as a floating window; `Super + T` tiles or un-tiles the active window. `Super + Shift + F` opens the file manager, producing a four-way tiled layout when combined with the above. `Super + Arrow` moves focus between windows (and recenters the mouse on the newly focused window). `Super + Shift + 2` moves the focused window to workspace 2; `Super + Shift + Alt + 2` does the same without switching to it. Holding `Super` + left-mouse-drag repositions a window; `Super` + right-mouse-drag resizes it freely. `Super + W` or `Super + Q` closes a window; `Ctrl + Alt + Delete` closes all windows. `Super + F` goes fullscreen, `Super + Alt + F` goes full-width (keeping the top bar), and `Super + Ctrl + F` goes fullscreen within the window (useful for video). ### Dwindle vs. scrolling layout Omarchy's default per-workspace layout is **dwindle**, which keeps every window on a workspace visible at once, shrinking them as needed. `Super + L` toggles a single workspace into the **scrolling** layout instead, where windows line up side by side beyond the visible screen edge. The layout choice is per-workspace and persists across restarts (also reachable via _Trigger > Toggle > Workspace Layout_ in the menu). To make scrolling the default, set it in `~/.config/hypr/looknfeel.lua`: ```lua hl.config({ general = { layout = "scrolling", }, }) ``` ### Grouping, popping, and scratchpad `Super + G` groups windows — every subsequently opened window joins the group until it's dissolved (`Super + G` again) or a window is pulled out (`Super + Alt + G`). Move between grouped windows with `Super + Ctrl + Arrow Left/Right` or jump directly with `Super + Alt + 1/2/3/4`. `Super + O` pops a window out of its workspace allocation, pinning it as a floating window that follows across workspaces (good for video players). A special **scratchpad** workspace drops down over the current workspace like a Quake console — toggle it with `Super + Grave` or `Super + S`, and send a window there with `Super + Shift + Grave` or `Super + Alt + S`; it's well suited to a terminal running an agent or controls you want without leaving the current workspace. ### The top bar The strip along the top of the screen is the **Omarchy bar**, part of the single long-running Quickshell shell process that also draws the menu, notifications, OSD popups, and the lock screen — which is why it themes consistently and panels open instantly (see [[concepts/theming]]). By default it has three sections: left holds the Omarchy logo/menu launcher and workspace indicators; center holds status indicators, the clock, keyboard layout (only shown with 2+ layouts configured), weather, and an update badge (only shown when an update is pending); right holds the system tray, agents icon (appears once AI coding usage is detected), Bluetooth, network, audio, display, and power. Nearly every widget responds to left, right, and middle click (and several to scrolling) — the manual calls out that "the right and middle buttons are where a lot of the good stuff hides": | Widget | Left | Right | Middle / scroll | | --- | --- | --- | --- | | Menu | Omarchy menu | New terminal | — | | Workspaces | Focus that 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 | | Agents | Agents panel | Launch your agent | Middle: next subscription | | Tray | Hover to reveal the drawer | Right on the chevron to manage | — | | Omarchy update | Run the update | — | — | Each bar icon opens a full keyboard-navigable panel (arrows move, Return activates, Tab steps to the neighboring panel, Escape closes), each with its own hotkey: `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), and `Super + Ctrl + 1-9` to toggle the nth panel in the right section (counting left to right, skipping the trayless icon). Two widgets — **Tailscale** and **Dropbox** — appear only after installing the matching service via _Install → Service_. The Tailscale panel connects/disconnects the tailnet, switches accounts, picks an exit node, and can send files to another machine over Taildrop (`s` to send, `c`/`n`/`d` to copy IP/name/DNS name); the same send is `omarchy tailscale send [file...]` from the terminal. The bar's center **indicators** cluster shows status glyphs (do not disturb, night light, a queued reminder, active screen recording, stay awake, dictation) only while active; hovering the bar center reveals inactive ones, and clicking one toggles that mode. Set `alwaysShow: true` on the widget to keep them always visible, or list specific `items` to show only some. The bar rearranges itself by direct manipulation: drag an empty patch toward a screen edge to relocate it (left/right/top/bottom, with widgets adapting to vertical compact forms); double-left-click empty bar space to toggle transparency; drag any widget to reorder or move it between sections. The same actions have CLI equivalents, useful for dotfiles: ```bash omarchy bar position bottom omarchy bar transparent toggle omarchy bar move omarchy.clock --section center --index 0 omarchy bar set omarchy.clock format "HH:mm" omarchy bar defaults # back to the shipped layout ``` Widgets are added/removed (rather than repositioned) via plugin commands — `omarchy plugin list` prints every widget id the shell knows, then: ```bash omarchy plugin enable omarchy.media --section center omarchy plugin disable omarchy.weather ``` `Super + Shift + Space` toggles the bar off/on without killing the shell (panels and hotkeys keep working) — also under _Trigger → Toggle → Menu Bar_. All bar configuration lives in `~/.config/omarchy/shell.json` under the `bar` key; **once that file exists, it is canonical** — there is no deep merge with future Omarchy defaults, so new default widgets in later releases won't appear automatically until `omarchy bar defaults` resets it. The same file also holds idle timings outside the `bar` key: `idle.screensaver` and `idle.lock`, in seconds (defaults: screensaver at 150s, lock at 300s). ### Hotkey reference `Super + K` shows all main keyboard bindings (`Super + Alt + K` for Tmux bindings, `Super + Ctrl + K` for Herdr bindings). Bindings are edited in `~/.config/hypr/bindings.lua`. Selected verbatim tables from the manual: **Navigating** | Hotkey | Function | | --- | --- | | `Super + Space` | Omarchy menu (apps and everything else) | | `Super + Alt + Space` | Apps menu | | `Super + Escape` | System menu (suspend, restart, etc) | | `Super + Ctrl + L` | Lock computer | | `Super + W` or `Super + Q` | Close window | | `Ctrl + Alt + Del` | Close all windows | | `Super + T` | Toggle window between tiling/floating | | `Super + J` | Toggle window position (horizontal/vertical) | | `Super + O` | Toggle popping window into sticky'n'floating | | `Super + L` | Toggle between dwindle and scrolling layout | | `Super + F` / `Super + Alt + F` / `Super + Ctrl + F` | Full screen / full width / full screen inside window | | `Super + 1/2/3/4` | Jump to specific workspace | | `Super + Shift + 1/2/3/4` | Move window to workspace | | `Super + S` / `Super + Grave` | Toggle scratchpad | | `Super + Arrow` | Move focus to window in direction of arrow | | `Super + Shift + Arrow` | Swap window with another in direction of arrow | | `Super + G` | Toggle window grouping | | `Super + Ctrl + Z` | Zoom in on screen (repeat for more zoom) | **System controls (selected)** | Hotkey | Function | | --- | --- | | `Super + Ctrl + A/B/W/D/P` | Audio / Bluetooth / Wifi / Display / Power panel | | `Super + Ctrl + S` | Share menu (via LocalSend) | | `Super + Ctrl + T` | Activity (btop) | | `Super + Ctrl + C` | Capture controls (screenshot/-recording/picker) | | `Super + Ctrl + E` | Emoji picker | | `Super + Shift + Ctrl + A` | Pick an AI agent | **Launching apps (selected)** | Hotkey | Function | | --- | --- | | `Super + Return` | Terminal | | `Super + Shift + Return` | Browser | | `Super + Shift + F` | File manager | | `Super + Shift + N` | Editor (Neovim) | | `Super + Shift + A` | AI (ChatGPT) | **Universal clipboard** | Hotkey | Function | | --- | --- | | `Super + C` | Copy | | `Super + X` | Cut (not in terminal) | | `Super + V` | Paste | | `Super + Ctrl + V` | Clipboard manager | These clipboard hotkeys work everywhere, including the terminal, unlike the traditional Linux split of `Ctrl+Shift+C/V` (terminal) vs. `Ctrl+C/V` (everywhere else). **Style** | Hotkey | Function | | --- | --- | | `Super + Ctrl + Shift + Space` | Pick a new theme | | `Super + Ctrl + Space` | Pick theme background | See [[concepts/theming]] for the full theming system these hotkeys drive. ### Keyboard, mouse, and trackpad configuration Hyprland input configuration is edited in `~/.config/hypr/input.lua`, reachable via _Setup > Input_ in the Omarchy menu (`Super + Space`); anything set there replaces Omarchy's defaults. Example: ```lua hl.config({ input = { -- Use multiple keyboard layouts and switch between them with Left Alt + Right Alt kb_layout = "us,dk", kb_options = "compose:caps,shift:both_capslock_cancel,grp:alts_toggle", -- Change speed of keyboard repeat repeat_rate = 40, repeat_delay = 600, -- Increase sensitivity for mouse/trackpad (default: 0) sensitivity = 0.35, touchpad = { -- Use natural (inverse) scrolling natural_scroll = true, -- Use two-finger clicks for right-click instead of lower-right corner clickfinger_behavior = true, -- Control the speed of your scrolling scroll_factor = 0.3, }, }, }) -- Scroll faster in the terminal o.window("(Alacritty|kitty|foot)", { scroll_touchpad = 1.5 }) ``` The full input option set is documented on the [Hyprland wiki](https://wiki.hypr.land/Configuring/Basics/Variables/#input). By default CapsLock is the compose key powering [quick emojis](#hotkey-reference) and text completions; changing `compose:caps` in `kb_options` (e.g. to `compose:ralt`) frees CapsLock to act as Caps Lock again and moves the compose key. Touchpad gestures (e.g. three-finger swipe to change workspaces) are enabled via `hl.gesture({ fingers = 3, direction = "horizontal", action = "workspace" })`. Dell XPS laptops with a haptic touchpad can set click strength (low/mid/high) under _Trigger > Hardware > Touchpad Haptics_. Omarchy runs the [fcitx5](https://fcitx-im.org/) input method framework in every session (it's what powers CapsLock compose sequences), so non-Latin input just needs an engine installed via `omarchy pkg add` (e.g. `fcitx5-mozc` for Japanese, `fcitx5-chinese-addons` for Chinese) plus `fcitx5-configtool` to register it. To use ALT as SUPER instead of the primary meta key, add `altwin:swap_alt_win` to `kb_options`. ## Key Parameters - **Super** — the anchor key for nearly all hotkeys. - **Default layout**: dwindle (per-workspace, toggled to scrolling with `Super + L`). - **Bar config file**: `~/.config/omarchy/shell.json` (canonical once it exists — no deep-merge with future defaults). - **Input config file**: `~/.config/hypr/input.lua`. - **Bindings file**: `~/.config/hypr/bindings.lua`. - **Idle timings**: `idle.screensaver` (default 150s) and `idle.lock` (default 300s) in `shell.json`. ## When To Use Learn the tiling model and the top bar first (this page) before customizing [[concepts/the-menu]] entries or [[concepts/theming]]. Reach for `Super + K` whenever a binding is forgotten — the manual and this page both treat it as the one hotkey worth memorizing. Edit `input.lua` when adjusting repeat rate, pointer sensitivity, multiple keyboard layouts, or trackpad gestures; edit `shell.json` (or use `omarchy bar`/`omarchy plugin` commands) when customizing the bar for a dotfiles setup (see [[concepts/omarchy-cli-and-shell]]). ## Risks & Pitfalls - Once a user creates their own `shell.json`, Omarchy stops deep-merging future default bar layouts into it — new widgets shipped in later releases won't appear until `omarchy bar defaults` resets the file. - A broken or partially-edited `bindings.lua`/`input.lua` can affect the entire input experience since these files fully replace Omarchy's defaults rather than patching them. - Users expecting overlapping/floating windows by default will be surprised; `Super + T` is the escape hatch for genuinely needing a floating window, but tiling is the norm. - The scratchpad, grouping, and popping features are easy to forget exist since they're not surfaced anywhere but the hotkey list and menu — `Super + K` is the reliable way to rediscover them. ## Related Concepts - [[concepts/coming-from-mac-or-windows]] — the mental-model translation this system assumes - [[concepts/the-menu]] — the `Super + Space` menu referenced throughout - [[concepts/theming]] — theme/background hotkeys and shell-wide styling - [[concepts/omarchy-overview]] — Hyprland and Quickshell as the underlying stack ## Sources - raw/github_doc-manual-04-navigation-md.md - raw/github_doc-manual-05-the-top-bar-md.md - raw/github_doc-manual-07-hotkeys-md.md - raw/github_doc-manual-34-keyboard-mouse-trackpad-md.md - raw/github_release-v4-0-0.md --- title: "Omarchy CLI and Shell" type: concept tags: [cli, system, shell, extension, power-user, foundational] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-manual-14-omarchy-cli-md.md", "raw/github_doc-manual-19-shell-tools-md.md", "raw/github_doc-manual-20-shell-functions-md.md", "raw/github_doc-manual-32-shell-plugins-md.md", "raw/github_doc-docs-cli-router-md.md", "raw/github_doc-docs-omarchy-shell-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- ## Definition Omarchy has two command-line-adjacent layers that work together: the **`omarchy` CLI**, a single entry point that reaches every group of internal tooling (`omarchy theme set`, `omarchy screenshot`, `omarchy plugin add`, and hundreds more), and **`omarchy-shell`**, the long-lived [Quickshell](https://quickshell.org/) process that renders the bar, panels, overlays, menus, and headless services as a plugin host. Around both sits a layer of enhanced shell tools, shell functions, and third-party shell plugins that make the terminal and desktop faster to drive by hand or by script. ## How It Works ### The CLI router `bin/omarchy` is a router, not a registry you maintain by hand: every executable file named `bin/omarchy-*` is automatically a command, and its filename is its route. `omarchy-theme-set` splits at the first hyphen into group `theme`, name `set`; a single-segment stem like `omarchy-update` is the root command of its own group. Metadata comments in the file's first 80 lines (documented in `agents/skills/command-metadata.md`) can rename a route, mark it hidden (`# omarchy:hidden=true`), or flag it as requiring sudo — but even without any metadata, a command still gets a working filename route and a generated summary. Dispatch tries a fast path first: it joins argument words with hyphens and stats for a matching executable (`omarchy theme set foo` probes `omarchy-theme-set-foo` then `omarchy-theme-set`), resolving without reading any metadata at all — this keeps plain dispatch fast even with hundreds of binaries installed. Only when the fast path fails (renamed routes, aliases) does the router load all metadata and fall back to a longest-prefix match against the full route table. Resolution is always `exec`: the router process is replaced, so the invoked binary sees only the leftover arguments and its own exit code is what the shell gets back. A few dispatch rules matter for scripting: - `--help`/`-h` is intercepted anywhere in the leftover arguments (not just first), unless a bare `--` ends the scan, after which everything belongs to the command. - `--json` alongside `--help` switches help to a JSON record; `--json` alone is a normal argument. - A command with required arguments and none supplied shows help instead of running (`omarchy theme set` prints usage rather than prompting interactively). - Two routes claiming different binaries is a silent collision (first registration wins); `omarchy commands --check` — the metadata lint run by `test/cli` — is what surfaces it, along with missing explicit `# omarchy:summary=` lines and invalid boolean metadata. ### Exploring the CLI Running `omarchy` alone prints the command center: common commands (`omarchy update`, `omarchy theme list`, `omarchy theme set `, `omarchy font list`, `omarchy screenshot`, `omarchy debug`) plus a list of groups (`agent`, `audio`, `bar`, `battery`, `bluetooth`, `branch`, `branding`, `brightness`, `capture`, `channel`, `clipboard`, `cmd`, `config`, `debug`, and more). `omarchy ` drills into that group's commands, and every command and group accepts `--help`. `omarchy commands [--all] [--json] [--markdown]` introspects the whole router: `--all` includes hidden plumbing commands (used for install-time steps like `omarchy apply hardware` that shouldn't appear in normal listings), and `--json` returns full records (route, binary, group, name, summary, flags, args, examples, aliases). The top-level group listing itself is driven by a hand-curated `GROUP_DESCRIPTIONS` table, which is also why some groups (like `apply`/`provision`) route correctly but never appear in a listing. The Omarchy menu itself is scriptable through the CLI: `omarchy menu` opens it at the root, `omarchy menu summon style.theme` jumps straight to the theme picker, `omarchy menu toggle system` opens (or closes, if already open) the system menu, and `omarchy menu close` dismisses it — handy for custom keybindings. See [[concepts/the-menu]] for the menu itself. ### omarchy-shell: the desktop as plugins The whole visible desktop — bar, dropdown panels, fullscreen overlays (emoji picker, clipboard manager), the Omarchy menu, the lock screen, the polkit dialog, and headless services (battery watcher, night-light warmer) — is a plugin running inside one long-lived `omarchy-shell` process. Hyprland autostart launches it via `omarchy-launch-shell`; `omarchy-restart-shell` restarts it. Any CLI that needs to talk to the running shell goes through IPC — `omarchy-shell` forwards a call and fails if the shell isn't running (`-q` makes that failure quiet/best-effort; `OMARCHY_SHELL_IPC_TIMEOUT` bounds how long it waits). A plugin declares one or more **kinds** in its `manifest.json`: | Kind | What it is | |------|------------| | `bar-widget` | A component the active bar drops into a section | | `bar` | A full bar that can replace the built-in `omarchy.bar` | | `panel` | A persistent or summoned floating window (e.g. an OSD) | | `overlay` | A fullscreen overlay (e.g. the background picker) | | `menu` | A summoned menu surface | | `service` | A headless singleton with no UI | Only one full `bar` is active at a time (`bar.id` in `shell.json`); panels, overlays, and menus load on summon; first-party `service` plugins load at startup. A plugin can declare several kinds at once — the media plugin is both a `service` and a `bar-widget`. Configuration lives in `~/.config/omarchy/shell.json`. When no user file exists, the shipped defaults (`config/omarchy/shell.json`) are used verbatim; once a user `shell.json` exists, it is canonical and replaces those defaults wholesale — there is no deep merge, so it must carry every entry it wants active: a bar layout under `bar.layout.
`, a third-party plugin under `plugins[]`, or a disabled first-party plugin under `disabledPlugins[]`. CLI tooling (e.g. `omarchy bar move`/`omarchy bar set`, and `omarchy bar defaults` to reset to the shipped file) is what keeps a customized file complete rather than requiring hand-maintenance of the whole document. It also carries the idle timings block (seconds since idle began, e.g. `idle.screensaver` / `idle.lock` — see [[concepts/productivity-tools]]) and the active bar's `id`, `position`, and `transparent` flag. Bar widgets and other visual theme tokens (colors, spacing, typography) live in a separate `shell.toml` per theme — see [[concepts/theming]] for that layer. The shell answers a small IPC method set over `omarchy-shell shell ...` — `ping`, `summon`/`hide`/`toggle `, `call `, `rescanPlugins`, `reloadConfig`, `applyTheme`, `setPluginEnabled`, `enablePlugin`, `listPlugins`, `listShellConfig`, among others — which is what the `omarchy plugin` and `omarchy bar` command groups drive under the hood. A one-off bar addition doesn't need a full plugin: an inline `bar.layout.
` entry with `"type": "command"` runs a script on an interval and renders its plain-text or Waybar-style JSON output, or `"type": "qml"` loads a custom QML `Item` from `~/.config/omarchy/bar/modules/.qml`. ### Plugin lifecycle First-party plugins ship under `$OMARCHY_PATH/shell/plugins/`; anything you add lives in `~/.config/omarchy/plugins/`. Both are discovered the same way at startup. Plugin ids are namespaced — built-ins start with the reserved `omarchy.` prefix (`omarchy.clock`, `omarchy.network`, `omarchy.notifications`), so a third-party plugin can never collide with one. ``` omarchy plugin list [--json] omarchy plugin enable omarchy.tailscale omarchy plugin disable omarchy.weather omarchy plugin add https://github.com/acme/omarchy-weather.git [--enable] [--yes] omarchy plugin update [acme.weather] omarchy plugin remove acme.weather omarchy plugin clone omarchy.clock [--edit] omarchy plugin validate ./my-plugin ``` Enabled state differs by plugin kind: a third-party plugin is enabled exactly when its id appears somewhere in `shell.json` (a bar layout entry, `plugins[]`, or `bar.id`); a first-party plugin that isn't a bar widget is on by default and only turns off by being listed in `disabledPlugins[]`; a full bar has no off state at all — enabling one just replaces the active bar. `omarchy plugin add` clones a repo into a staging directory, validates its `manifest.json`, refuses the install if the id is already claimed, and moves it into `~/.config/omarchy/plugins//`. It never runs code from the plugin, never executes an install hook, and never asks for sudo. `omarchy plugin update` (no id = update everything git-managed) shows a diff before fast-forwarding, and refuses if local changes can't be fast-forwarded past. `omarchy plugin remove` disables first, then deletes a git checkout or unlinks a symlink; a hand-made plugin folder with no git repo is moved to a timestamped backup instead of being deleted outright. To customize a built-in widget without it being overwritten on the next update, **clone** it rather than editing files under `$OMARCHY_PATH`: `omarchy plugin clone omarchy.clock` copies it into `~/.config/omarchy/plugins/.clock/`, renames it, enables it, and switches the shell over while preserving the existing widget's bar position. Calls to the original `omarchy.clock` id route to the clone automatically, and `omarchy plugin remove .clock` restores the built-in (`dhh.clock` in the manual is just DHH's own example — substitute your actual username). Saving any file under `~/.config/omarchy/plugins/` hot-reloads that plugin's code. `omarchy plugin validate ./my-plugin` runs the same checks the shell does at load time: schema version, required fields, a non-reserved id, entry points that exist and are safe relative paths, and no symlinks anywhere inside the plugin folder. The community directory for sharing and discovering plugins is [omarchyplugins.com](https://omarchyplugins.com). ### Shell tools Beyond standard Linux tools, Omarchy ships enhanced replacements, most exposed as short aliases: | Tool | Replaces | Use | |------|----------|-----| | [fzf](https://junegunn.github.io/fzf/) | — | Fuzzy find files with `ff` (with preview); `Ctrl + R` fuzzy-searches command history; also drives Neovim's `Space Space` | | [Zoxide](https://github.com/ajeetdsouza/zoxide) | `cd` | Remembers visited directories — `cd oma` can jump to `~/.config/omarchy` after one visit | | [ripgrep](https://github.com/BurntSushi/ripgrep) | `grep` | `rg `; also drives Neovim's `Space S G` | | [eza](https://eza.rocks/) | `ls` | Aliased as `ls`; `lt` = two-deep nested listing, `lsa` = with hidden files, `lta` = both | | [fd](https://github.com/sharkdp/fd) | `find` | `fd person.rb` (current tree), `fd person.rb /` (whole filesystem), add `-H` for hidden dirs too | | [bat](https://github.com/sharkdp/bat) | `cat` | Syntax highlighting + paging; also colors man pages and renders `ff` previews | | [tldr](https://tldr.sh/) | `man` (for examples) | `tldr tar` gives example invocations instead of the full manual | | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | — | `yt-dlp ` downloads video from YouTube and hundreds of other sites | | [try](https://github.com/tobi/try) | — | Date-stamped experiment directories under `~/Work/tries`, accessed via `try` | ### Shell functions Functions bundle common multi-step operations: - **Compression**: `compress [file/dir]`, `decompress [file.tar.gz]`. - **Drives**: `iso2sd [image.iso]` (interactive drive picker for a bootable SD/USB), `format-drive [device] [name]` (single exFAT partition, cross-OS — destructive, run without args to list drives first). - **Dev layouts** (Tmux-based, programmable panes): `tdl [ai]` builds a three-pane layout (`$EDITOR` + AI agent + terminal) — `tdl c` for opencode, `tdl cx` for Claude Code, or `tdl c cx` for two agents at once; `tds` is a four-pane square (editor, live diff watcher via `hunk diff --watch`, terminal, opencode); `tdlm [ai]` repeats `tdl` for every subdirectory, navigated with `alt + 1/2/3/...`; `tsl [count] [command]` tiles a grid of panes running the same command (e.g. a swarm of agents). The same four layouts exist for [Herdr](tuis-guis-and-browsers.md) as `hdl`, `hds`, `hdlm`, `hsl`. See [[concepts/terminal-and-neovim]] for the terminal/tmux context these run in, and [[concepts/ai-and-dev-tools]] for the agents they launch. - **Git worktrees**: `ga [branch]` creates a worktree+branch next to the current repo and jumps in; `gd` removes the current worktree and branch (with confirmation). - **Rsync watchers**: `rsw [source] [destination]` starts a background watcher that syncs on change (destination can be remote, e.g. `rsw ~/Work/app nyc-dev:Work/app`); `lsw` lists active watchers; `dsw` stops them all. - **SSH port forwarding**: `fip [host] [port...]` forwards remote ports to localhost (useful for testing secure-context features like WebSockets without TLS certs); `dip` disconnects; `lip` lists active forwards. - **SSH reconnection**: `ssh` itself is wrapped to clean up the terminal if a connection carrying a remote tmux/Herdr/editor session dies, and auto-reconnects an interactive session that drops (`Ctrl-C` stops the retry loop). ## Key Parameters - **Route resolution order** — filename fast path (stat-based, no metadata read) tried first; metadata-driven longest-prefix match only on a miss. - **`OMARCHY_SHELL_IPC_TIMEOUT`** — bounds how long a CLI command waits on shell IPC. - **Plugin id namespace** — `omarchy.*` is reserved for first-party plugins; third-party ids must avoid it. - **`shell.json` merge rule** — no deep merge; once present it is fully canonical and replaces the shipped defaults wholesale, so it must carry every entry it wants active (CLI tooling like `omarchy bar defaults` keeps it complete). - **`disabledPlugins[]` vs presence-based enabling** — first-party non-bar plugins are opt-out (listed to disable); third-party plugins and full bars are opt-in (listed to enable). - **Command metadata flags** — `# omarchy:hidden=true`, `# omarchy:requires-sudo=true` (must be `true` or omitted, never `false`), `# omarchy:summary=`, `# omarchy:name=`. ## When To Use - Scripting or automating Omarchy behavior — including having an AI coding agent read/adjust configuration through `omarchy` commands instead of hand-editing files (see [[concepts/ai-and-dev-tools]]). - Building a custom bar widget, panel, or overlay, or modifying a built-in one safely via `omarchy plugin clone` instead of editing package files. - Speeding up everyday terminal navigation and search (`ff`, `rg`, `fd`, `bat`, `zoxide`) or setting up a multi-pane AI-agent development workflow (`tdl`, `tsl`). - Diagnosing "why didn't my keybinding/command do what I expected" — `omarchy --help` and `omarchy commands --all --json` show exactly what the router resolved. ## Risks & Pitfalls - **Plugins run as unsandboxed code** inside the long-lived shell process, with everything your user account can reach. Only add plugin repos you're willing to run, and read the code before enabling — `omarchy plugin add` warns explicitly and lands plugins disabled by default. - **Editing built-in plugin files directly under `$OMARCHY_PATH`** is a dead end: the next update overwrites them. Clone instead. - **Route collisions are silent** at runtime (first registration wins); only `omarchy commands --check` reports them, so a bad rename can hide a real bug until lint is run. - **`format-drive` is destructive** — it wipes an entire disk to a single exFAT partition; always run it argument-less first to confirm which device you're targeting. - **`omarchy plugin update` refuses to fast-forward past local changes** you've made directly in a cloned plugin's checkout, so hand-edits outside of a proper clone-and-commit workflow can block updates. - Because dispatch uses `exec`, a command's own exit code is what you see — there's no router-level wrapping to catch failures underneath it. ## Related Concepts - [[concepts/the-menu]] — the graphical counterpart the CLI can drive via `omarchy menu` - [[concepts/theming]] — `shell.toml` theme tokens, colors.toml, and templated theme files that sit alongside `shell.json` - [[concepts/terminal-and-neovim]] — the terminal/tmux environment where shell tools, functions, and `tdl`-style layouts are actually used - [[concepts/ai-and-dev-tools]] — the coding-agent CLIs that `tdl`/`tsl` launch, and the mise-managed lazy-install stub pattern shared with `omarchy-mise-install` - [[concepts/hyprland-and-window-management]] — Hyprland autostart is what launches `omarchy-shell` ## Sources - raw/github_doc-manual-14-omarchy-cli-md.md - raw/github_doc-manual-19-shell-tools-md.md - raw/github_doc-manual-20-shell-functions-md.md - raw/github_doc-manual-32-shell-plugins-md.md - raw/github_doc-docs-cli-router-md.md - raw/github_doc-docs-omarchy-shell-md.md - raw/github_release-v4-0-0.md --- title: "Omarchy Overview" type: concept tags: [overview, foundational, well-established, user] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-readme-md.md", "raw/github_doc-manual-01-welcome-to-omarchy-md.md", "raw/github_doc-manual-02-getting-started-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- # Omarchy Overview ## Definition Omarchy is a "beautiful, modern & opinionated" Linux distribution created by DHH (of Basecamp/37signals). It is built on top of [Arch Linux](https://archlinux.org/), the tiling window manager [Hyprland](https://hypr.land/), and the desktop construction kit [Quickshell](https://quickshell.org/). Rather than being a bare Arch+Hyprland setup the user assembles by hand, Omarchy ships as a complete, curated system: it is described as an "omakase" (chef's-choice) Linux distribution — the maintainers pick the defaults so the user doesn't have to. Its authoritative documentation is the manual in the `basecamp/omarchy` GitHub repository (mirrored to learn.omacom.io), and more information lives at omarchy.org. ## How It Works Omarchy combines three layers into one coherent product: - **Arch Linux** as the base OS and package ecosystem. - **Hyprland** as the tiling window manager — everything is keyboard-driven, windows tile automatically rather than floating and overlapping, and there is no dock or desktop-icon paradigm (see [[concepts/navigation-and-hotkeys]]). - **Quickshell**, the desktop construction kit that draws the top bar, the unified [[concepts/the-menu]], notifications, on-screen-display (OSD) popups, and the lock screen as one long-running process — which is why the whole desktop themes consistently and panels open instantly (see [[concepts/theming]]). On top of this base, Omarchy preinstalls a curated application set spanning editors (Neovim), browsers (Chromium), productivity apps (Obsidian, LibreOffice), media tools (Kdenlive, OBS Studio), and even a retro Winamp-style music player — described in the manual as "zero bloat... just everything I use." The system favors plain configuration files over settings panels, a package manager over downloaded installers, and terminal/TUI-heavy workflows over GUI-heavy ones. ## Key Parameters - **Base distribution**: Arch Linux. - **Window manager**: Hyprland (tiling by default). - **Shell/UI layer**: Quickshell (single long-running process for bar, menu, notifications, OSD, lock screen). - **Philosophy**: "Omakase computing" — opinionated defaults chosen by the maintainers rather than a blank-slate DIY build. - **Current documented release**: v4.0.0. - **License**: MIT. ## When To Use Omarchy is aimed at "modern, savvy computer users" who want a productive system out of the box without manually assembling an Arch+Hyprland rice from scratch. The manual is explicit that Omarchy is not trying to be as familiar as possible to Windows or macOS users — it's "trying to be beautiful and _better_," and embracing it means accepting a keyboard-centric, terminal-heavy, config-file-editing workflow (see [[concepts/coming-from-mac-or-windows]]). It suits users willing to invest a short adjustment period in exchange for a fast, aesthetically cohesive, and deeply customizable desktop (see [[concepts/theming]] and [[concepts/installation]] for getting started). ## Risks & Pitfalls - It is explicitly **not** designed to feel like Windows or macOS; users expecting drag-and-drop windows, a dock, or desktop icons will need to unlearn those habits (see [[concepts/coming-from-mac-or-windows]]). - The manual acknowledges that "developing an eye for the beauty of a TUI-heavy, theme-delighted, tiling-window-managed system like Omarchy can be an acquired taste" — it is aimed at users open to that adventure, not everyone. - Because it is opinionated, defaults are chosen for the user; someone wanting a maximally neutral or minimal Arch install may find Omarchy's curation (bundled apps, forced encryption defaults, etc.) more than they want (see [[concepts/installation]] for encryption defaults). ## Related Concepts - [[concepts/installation]] — how Omarchy is installed - [[concepts/coming-from-mac-or-windows]] — translating Mac/Windows habits to Omarchy - [[concepts/navigation-and-hotkeys]] — the keyboard-driven tiling workflow - [[concepts/the-menu]] — the unified Quickshell-based menu system - [[concepts/theming]] — the theming system that ties the desktop together ## Sources - raw/github_doc-readme-md.md - raw/github_doc-manual-01-welcome-to-omarchy-md.md - raw/github_doc-manual-02-getting-started-md.md - raw/github_release-v4-0-0.md --- title: "Plugins and Extension" type: concept tags: [extension, power-user, advanced, emerging] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-default-agents-skills-omarchy-plugins-md.md", "raw/github_doc-default-agents-skills-omarchy-hooks-md.md", "raw/github_doc-default-agents-skills-omarchy-capture-md.md", "raw/github_doc-default-agents-skills-omarchy-contributing-md.md", "raw/github_doc-manual-32-shell-plugins-md.md", "raw/github_release-v4-0-0.md"] confidence: medium omarchy_version: "v4.0.0" --- # Plugins and Extension ## Definition Since the v4.0.0 ("Quattro") rewrite of the desktop shell in [Quickshell](https://quickshell.org) (see [[summaries/release-digest]]), Omarchy exposes a formal extension surface: **bar/shell plugins** for widgets and overlays and **automation hooks** for running scripts on system events. This page also covers the **capture/sharing toolkit** (screenshots, recording, OCR, file sharing) and the **contribution path** for reporting bugs or submitting fixes upstream, since extension work, capture, and upstream contribution use overlapping tooling (debug logs, screen capture). ## How It Works ### Shell plugins (bar, notifications, idle) The bar, notification daemon, settings panel, and overlays all run inside a single long-running Quickshell process (`omarchy-shell`). Configuration surfaces: ``` ~/.config/omarchy/shell.json # User overrides: bar, plugins, idle ~/.config/omarchy/plugins// # User-owned shell plugins $OMARCHY_PATH/config/omarchy/shell.json # Canonical defaults ``` `shell.json` hot-reloads on save — no restart needed for layout changes. `idle.screensaver` and `idle.lock` are both expressed in seconds since user idle began (e.g., locking after ten minutes means setting `idle.lock` to `600`). Restart/refresh the whole shell with `omarchy restart shell` / `omarchy refresh shell`. **Bar layout** is managed with the `omarchy bar` command group, e.g. `omarchy bar move omarchy.clock --section right`; anything the commands don't cover is edited directly in `shell.json`, which hot-reloads. **Customizing a built-in widget**: never edit `$OMARCHY_PATH/shell/plugins/` directly. Instead, clone it into the user plugin directory: ```bash omarchy plugin clone omarchy.workspaces # Edit ~/.config/omarchy/plugins/.workspaces/; saved changes reload automatically. ``` Cloning switches the bar over to the cloned copy (e.g., `.workspaces`), which the user owns and which survives future updates. Any file saved under `~/.config/omarchy/plugins/` reloads automatically; if a change doesn't apply, `omarchy-shell shell rescanPlugins` forces a reload. Third-party bar plugins and even whole replacement bars install straight from git with `omarchy plugin add `, managed from _Setup > Plugins_ (add, clone, enable, disable, remove) — introduced as part of the v4.0.0 plugin ecosystem alongside [omarchyplugins.com](https://omarchyplugins.com/) (see [[summaries/release-digest]]). ### Automation hooks Hooks run scripts on system events — theme changes, updates, boot, low battery, and more. They live under `~/.config/omarchy/hooks/.d/`, one directory per event, holding any number of independent executable scripts (plus an optional flat `~/.config/omarchy/hooks/` file, which the runner executes first if present): ``` ~/.config/omarchy/hooks/ ├── battery-low.d/ # Low battery (percentage in $1) ├── font-set.d/ # After font change (font name in $1) ├── post-boot.d/ # After the desktop starts ├── post-update.d/ # During `omarchy update`, after system packages and migrations ├── pre-refresh-pacman.d/ # Before `omarchy refresh pacman` re-syncs packages └── theme-set.d/ # After theme change (theme slug in $1) ``` `omarchy hook install