In one line
Omarchy is an opinionated Linux distribution built on Arch Linux and Hyprland, bringing terminals, editors, AI coding tools, and themes into a connected developer desktop.
Repository: omacom/omarchy
A new development machine comes with decisions before you open any code. Choose a terminal and editor, align language versions, arrange windows, and adjust shortcuts, and the environment becomes a project of its own. Omarchy provides starting answers. Open a terminal and browser and their windows sit alongside each other; keyboard navigation connects file exploration, editing, and conversations with an AI agent.
What interests us as a builder community is how these defaults fit together. Arch provides the base, Hyprland arranges windows, and Quickshell underpins desktop elements such as the bar and menu. Themes coordinate the editor and terminal, menus install development environments, and system snapshots provide a route back after updates. If a screenshot catches your attention, explore how a day's work moves through that desktop too.
For a first attempt, open one familiar project on a spare machine. Follow your usual sequence of editing, testing, and viewing results in a browser. Notice whether windows are easier to find, essential applications and input methods work, and settings are accessible when something needs adjustment. Read the installation options and hardware requirements before erasing a computer you already use.
What can you do with it?
Started by DHH, Omarchy takes its name from the idea of omakase: the creator chooses and prepares a set of tools. The official introduction centers on Arch, Hyprland, and Quickshell. Arch supplies the package and system foundation, Hyprland arranges windows as tiles, and the shell built with Quickshell supplies the bar and menu. Applications for development and everyday work complete the setup.
You can explore repositories in a terminal, edit code, and view results in a browser. Foot is the default terminal, and Neovim includes a setup based on LazyVim. Chromium, Obsidian, and LibreOffice support browsing, notes, and documents. There are graphical applications and a file manager alongside the terminal; keyboard shortcuts connect launching and moving between them.
There is room to choose familiar tools. The development tools documentation describes installing VSCode, Cursor, Zed, and other editors under Install > Editor, then selecting a default under Setup > Defaults > Editor. Alacritty, Ghostty, and Kitty are terminal alternatives. If learning Neovim while changing operating systems feels like too much, keep your familiar editor and concentrate on window management first.
Choose language environments under Install > Development. Options include Ruby on Rails, JavaScript runtimes, Python, Go, and Rust, with many managed through mise. Docker and Docker Compose are included. Lazygit comes preinstalled, while gh, uv, and many coding agents are installed through mise on first launch. Distinguishing an available launcher from an already downloaded program helps explain that first-run download.
The useful question is how these choices work together: finding files, searching contents, moving windows, and reviewing results. If selecting every component yourself is part of the appeal, or preserving an existing configuration is essential, account for the time needed to adopt and adjust Omarchy's defaults.
Installation: choose the disk carefully
The official getting started documentation uses an ISO. Download it from the official installation page, which also links SHA-256 and signature files for verification. Match the image and verification material to the same release. Begin with that ISO workflow rather than an unrelated shell command intended to modify your existing operating system.
A full-disk installation erases the selected drive, including its files and existing operating system. Back up to a separate storage device and prepare recovery material first. Writing the ISO also erases the existing contents of the target USB stick. Verify device names and capacities so the installation target cannot be confused with an external backup drive. Encryption protects data after installation; it cannot undo erasure.
The official sequence is:
- Download and verify the ISO. The documentation suggests balenaEtcher on Mac or Windows, and caligula on Linux, to write it to USB.
- Boot from that USB. The official instructions say to disable Secure Boot and/or TPM in the BIOS. On managed hardware, first align this with device security policy and the recovery requirements of the existing operating system.
- Answer and review the configuration questions. Select the drive and installation space, then read the target and installation mode again at the formatting confirmation.
- Boot into the installed environment. With the default encrypted installation, unlock the drive at startup. Prepare a wired keyboard or one with a 2.4 GHz dongle: a Bluetooth-only keyboard cannot enter the password at this stage.
The current manual covers both using a whole drive and installing into unallocated space. For Windows coexistence, follow the dual-boot instructions to shrink a Windows partition, then choose Free space install in the installer. Continuing with full-disk installation selected can destroy the existing data.
That documentation also requires disabling BitLocker and allowing decryption to finish. Understand the existing Windows encryption and recovery requirements before proceeding. Unallocated space does not replace a backup. Intel Macs have separate constraints, so read the Mac support section below rather than applying the Windows instructions to them.
Before thinking about installation speed, decide which disk can be erased and what must remain recoverable. Preserve unpushed project changes as well as non-code material such as browser profiles and authentication methods. Preparing these before opening the installer keeps the first day's task manageable.
Learn the first keyboard routes
The navigation documentation starts with Super + Space. Super is usually the Windows key on a PC keyboard and the Command key on a Mac keyboard. The menu provides access to applications and settings, so you can begin before memorizing every shortcut. Use Super + K to see the key list.
| Action | Default shortcut |
|---|---|
| Open the Omarchy menu | Super + Space |
| Open a terminal | Super + Return |
| Open a browser | Super + Shift + Return |
| Show shortcuts | Super + K |
| Move focus between windows | Super + Arrow |
| Change workspace | Super + Number |
| Send the current window to a workspace | Super + Shift + Number |
| Toggle the current window between tiled and floating | Super + T |
One terminal can occupy the screen; a browser opened next takes a place alongside it. Try Super + J to stack them vertically. Before manually adjusting every width, see whether your usual two or three windows are readable in the default arrangement. A long log and a small preview may need different amounts of space.
Give workspaces simple roles: code and execution results on the first, reference material on the second, for example. This is a possible working arrangement rather than a requirement. If too many windows make text cramped, split them across workspaces before learning more shortcuts.
The mouse remains useful. Hold Super to move or resize windows, and float individual windows when appropriate. Start by getting comfortable with opening a window, moving focus, and returning to a workspace. Keyboard navigation can become familiar a few actions at a time.
Scenario 1: open a project on a fresh development machine
Setting up a new laptop can mix previously used versions with newly installed ones. Prepare the editor, language environment, and repository tools in sequence. Make running and testing one project the first goal; add your usual extensions and shell customizations afterwards.
Choose a default editor first. If you keep Neovim, start with file finding and search in the official Neovim documentation: Space Space finds files, Space S G searches contents, and Space G G opens Lazygit. If a graphical editor is more familiar, install it from the menu, make it the default, and open the same project there.
Next, inspect the project's required language version. The development tools documentation gives this Ruby installation example:
mise use -g ruby
It installs Ruby and makes it the global default. For a project with a .ruby-version file, the documentation also gives mise i from the project root. Keep the project requirement distinct from the machine-wide default. A globally installed latest version does not establish compatibility with your team's project. Follow that project's README for dependency installation and tests.
For GitHub work, the same official documentation starts with gh auth login, which installs the CLI on first use and continues with authentication. Once inside a repository, concentrate on finding files and reading changes. In the shell tools documentation, ff finds files with a preview, Ctrl + R searches command history, and rg searches file contents.
For a local database, explore Install > Development > Docker DB. Docker and Compose are included, but the default user is outside the docker group. The official documentation uses sudo on the command line and explains that Docker group membership can effectively grant administrator access. Understand the default before changing membership to match an old machine's behavior.
Set concrete completion conditions: the project opens, runs with its required runtime, produces test results you can inspect, and shows its local output in a browser. Preserve the necessary steps in the team README so another machine can follow them. Personal themes and key choices can remain personal preferences.
Scenario 2: keep the editor, AI, and execution results together
AI-assisted coding often means moving between a conversation, source code, and execution results. Omarchy's tiling and terminal setup can support that work: an editor beside a coding agent, with test output in another window. Compare this with the Superpowers development workflow when thinking about both the order of work and the space used to review it.
The AI manual documents launchers for Claude Code, Codex, OpenCode, Grok, and other agents. Most install their CLI through mise on first launch, followed by authentication with the service. Preparing a tool and obtaining model access are separate steps. Review the selected provider's account requirements, pricing, and your organization's rules for sending code.
Choose a default agent under Setup > Defaults > Agent; choosing one that needs installation starts that process too. The official documentation says Omarchy's default-agent launch paths and some short aliases use automatic approval modes. Do not assume a shortcut preserves the approval behavior you normally use. Understand each CLI's permissions and approval settings, then begin with a defined scope in a separate trial repository.
For more consistent terminal layouts, explore Tmux in the terminal documentation. Open a new session with Super + Alt + Return, then press Ctrl + Space followed by s to see sessions. Tmux can keep a session available after closing its terminal window, helping you return to conversations and server output. This does not mean processes survive a computer reboot.
The documented tdl function arranges an editor, a selected agent, and a terminal below. Start by seeing whether one agent's changes are easy to read before building an elaborate multi-agent screen. Simultaneous visibility of tests and code still leaves review to you. Compare the requested behavior, the actual diff, and the conditions covered by tests.
Keep the scope smaller when an agent works on the computer's configuration. Explaining the current monitor configuration has different consequences from editing it and restarting a related process. Establish the files to read, the intended change, and the way back before editing. Review commands from online configuration advice before running them as well.
A useful habit is keeping the request and its evidence visible together. Open the changed file, read the test output, and turn missing conditions into a specific next request. Observe how your repeated window transitions change; changing operating systems alone does not establish better code or faster review.
Scenario 3: move a development task from macOS
Start with where familiar actions go. The Mac and Windows transition documentation maps launching to Super + Space and copy and paste to Super + C and Super + V, including in the terminal. Try a short task involving an open editor and copied reference material to discover what transfers and what needs practice.
Desktop behavior has differences. Default tiling places windows without overlap and lets you jump directly to numbered workspaces. Finding applications in a Dock and looking behind windows may be habits to change. Complete one task, such as editing while reading documentation, to judge the new arrangement through actual work.
Before installing on Mac hardware, read Mac support. It covers Intel Macs and known device limitations, and says direct installation on M-series Macs is unsupported. Apple Silicon users can explore the virtual-machine instructions linked under Try on Mac on the official homepage. Learning the desktop in a VM and installing directly on the Mac are separate possibilities.
The Intel Mac installation instructions say Omarchy becomes the only installed operating system, wiping the drive and making macOS unbootable. The general PC free-space instructions do not establish coexistence on a Mac. Prepare recovery options and read the relevant T1 or T2 limitations and boot settings. Similar product names do not establish identical audio and input-device support.
For builders who type Korean, input methods belong on the first-day list. The input documentation says choosing Korean during installation configures standard two-set Hangul. Explore Setup > Typing > Input Methods and switch with Super + I. Desktop language and input methods are separate, so an English menu does not prevent preparing Korean input.
Try typing and switching input in the browser, editor, and terminal. Test the Korean/English and Hanja keys you normally use, along with familiar shortcuts. With an external monitor, inspect resolution, scaling, and the arrangement after reconnecting it. The monitor documentation provides the Setup > Monitors route to configuration.
Finally, list the applications essential to your work. A running repository and development server are only part of a day that also includes meetings, screen sharing, document exchange, and company security tools. After completing a personal project task, add those requirements one by one. Any reason to retain the existing machine becomes easier to explain in concrete terms.
Themes and configuration: build on the defaults
The appeal of themes is changing several applications together. Choose one under Appearance > Theme or with Super + Ctrl + T; supported surfaces include the terminal, Neovim, bar, and menu. Try the same project across several windows to see how the colors and visual atmosphere connect.
Applications can require different steps. The manual says to select the Omarchy theme manually inside Obsidian. Test themes using the applications you work in, paying attention to code, selected text, and error visibility. A good screenshot and comfortable distinctions over a long working session are different judgments.
Configuration centers on ~/.config, as explained in the dotfiles documentation. Files have specific roles: ~/.config/hypr/bindings.lua for keybindings, monitors.lua for displays, and input.lua for input devices. The Setup menu opens the relevant configuration so you can begin without memorizing every path. Start with an understandable change such as one frequently used key or display scaling.
Distinguish your configuration from package-provided defaults. The documentation recommends overrides in ~/.config rather than edits under /usr/share/omarchy, where a package update can overwrite changes. When backing up or versioning dotfiles, select the personal settings you need and keep credentials and secrets out of that collection.
Updates and recovery are part of the environment
An Arch-based desktop raises questions about updates. The official update documentation uses Update > Omarchy to update the system and packages together. Snapshots, migrations, and configuration updates are part of that process. A separate system-wide upgrade through a familiar package manager can bypass this coordination.
New installations start on stable. The manual describes official releases and a separate stabilization mirror, while edge and dev are for people accepting faster changes and greater recovery responsibilities. On a first development machine, establish that the project and hardware work on the default channel. Balance trying new features against reliably completing daily work.
Read the limits in the system snapshots documentation. Updates automatically create snapshots; the Limine bootloader lets you boot an earlier state and proceed with restoration. The documented omarchy-snapshot create also creates a manual snapshot. Locate the boot menu and recovery instructions before a failure makes them urgent.
System snapshots restore the root filesystem and do not restore /home. Personal files and ~/.config remain in place, so snapshots cannot recover deleted project files. An older application may also need adjustment if the retained configuration uses a newer format. Prepare separate backups for code, documents, and personal settings alongside system recovery. This snapshot feature requires a Limine installation and does not automatically apply to other bootloaders.
Resetting configuration is another distinct operation. The reinstall route described in the update documentation can overwrite user configuration changes. If something breaks, read what a recovery operation changes and preserve the needed settings before using it. Knowing which parts can be restored is part of learning a new desktop.
Which builders should explore it?
A useful starting point: Individual builders comfortable with terminals and keyboards, who want to prepare their development tools and desktop together. Working across code, documentation, and AI conversations, or setting up a spare PC, offers a focused first attempt. There is plenty to explore if you enjoy trying defaults and then adjusting them through configuration files.
Time to invest: Window management, configuration files, packages, and language versions all take learning. A quick installation does not establish that your daily work has moved successfully. Explore whether the default applications fit and whether the workflow remains useful after removing extras. The official FAQ describes removing packages and web apps; using every included application is optional.
Reasons to consider another setup first: Little time for operating-system maintenance, or mandatory company security software and specialized applications. Establish Linux approval and device-management requirements before migration. Direct installation on an Apple Silicon Mac also falls outside the documented support. Compare another distribution or adding the needed tools to your current operating system.
Security defaults: The security documentation describes default disk encryption and a firewall. Incoming traffic has a LocalSend port exception, and SSH is off until enabled. Review both these defaults and services you add. Encryption does not automatically restrict the permissions of programs or agents running as the signed-in user.
Licensing and cost: The Omarchy repository uses MIT. Read LICENSE notice requirements for modification and redistribution, and review the separate licenses of included or additional software. Model usage, paid applications, and external services have their own costs and terms. Separate the operating system's open source license from permission to use connected services.
Our suggested closing exercise is simple: finish one familiar project task, then note which actions became easier and which required more learning. Judge keyboard comfort alongside the tools your work needs. That leaves a practical basis for deciding whether the appealing desktop should become your everyday workspace.
Original sources and further reading
- Omarchy repository and official manual
- ISO download, installation, and dual boot
- Mac support and troubleshooting
- Official homepage demonstration: Omarchy Quattro by David Heinemeier Hansson, for exploring window arrangements, application switching, and desktop movement.
- Releases and MIT LICENSE
- Continue with the Superpowers development workflow and memory and recurring work in Hermes Agent.
Wrapping up
The Hypemarc Builder Community will keep sharing the developer tools and open source projects we explore. We'll continue gathering useful resources to share with fellow builders.
- Open chat: AI Builders
- Adoption advice and inquiries: Contact form
- Get the next post: Blog RSS · AI resource library