omacom/omarchy installation guide

Omarchy on macOS Tahoe (Apple silicon): compatibility-first installation guide

The short answer

**There is no source-supported way to install this repository directly on macOS Tahoe, including on an Apple-silicon Mac.**

Omarchy describes itself as a “Linux distribution,” and the repository metadata similarly calls it “Beautiful, Modern & Opinionated Linux.” The supplied files document a Linux desktop built around Hyprland and Quickshell. They also refer to Linux-specific components such as SDDM, PAM, Polkit, PipeWire, UPower, `powerprofilesctl`, system services, a firewall, Docker configuration, and Wayland clipboard tooling.

That is materially different from a normal Mac application. Omarchy is intended to provide an operating-system and desktop environment, not an app that can be copied into `/Applications` or installed over macOS.

The repository’s README links to manual chapters named **Mac support**, **Omarchy on...**, **Dual Boot Install**, and **Unattended Installs**, but the contents of those chapters were not supplied. A title or link alone does not establish that macOS Tahoe or Apple silicon is supported, nor does it supply a safe procedure. Consequently, this guide cannot responsibly provide Terminal installation commands, disk-partitioning steps, firmware changes, a virtual-machine recipe, or dual-boot instructions.

Classification relative to Claude Code

**Classification: runs alongside Claude Code; it is not shown to be a Claude Code extension.**

Omarchy is primarily a standalone Linux distribution and desktop environment. One supplied provisioning file lists `claude` among several coding-agent tools installed through Omarchy’s own `omarchy-mise-install` helper. Other listed agents include Codex, Crush, Copilot, OpenCode, Pi, Grok, and Ori.

Omarchy also ships an `omarchy.agents` bar widget. Its documentation says the widget displays usage records generated by agent-specific collectors. For Claude, the collector can read local Claude project transcripts, fallback statistics, and—when the Claude CLI is signed in—Anthropic’s OAuth usage endpoint. The panel can display limits and local activity and can launch an agent.

No supplied file documents a Claude Code plugin manifest, MCP server, Claude hook, Agent Skill, command package, or configuration edit that extends Claude Code itself. The reliable relationship is therefore that Omarchy can install, launch, and monitor Claude Code as one tool within its Linux environment. The bar panel is an Omarchy desktop feature, not evidence of a Claude Code extension mechanism.

What not to do on your Mac

Do not paste Omarchy’s Linux commands into the macOS Terminal. Commands such as `omarchy`, `omarchy-shell`, and `omarchy-mise-install` belong to an already installed Omarchy environment; the supplied evidence does not document them as macOS programs.

Also avoid improvising from individual installer fragments. The repository includes files that configure SDDM login, PAM, services, a firewall, snapshots, browser policy, Docker, and hardware-specific fixes. Those fragments are pieces of a larger Linux installation process, not independent Mac setup scripts. The supplied top-level README contains no installation command, and no supplied file explains which installer entry point a new user should invoke.

For the same reason, this guide does **not** recommend cloning the repository and running scripts from its `install/` directory. Although the public metadata supplies an HTTPS clone URL, it does not say that cloning and executing the checkout is the supported installation procedure. Running partial system-provisioning scripts outside their intended environment could leave a system misconfigured.

Safe path for a macOS Tahoe user

1. Keep macOS intact

Do not erase, repartition, or modify your Mac based on the supplied material. No first-party procedure for Apple-silicon Macs is available in the evidence, and the repository does not provide a supported-machine or architecture matrix here.

“Mac support” in the manual’s table of contents is not enough to infer what models, processors, boot methods, or limitations it covers. In particular, it must not be treated as proof that Apple silicon can boot Omarchy or that a given virtualization product is supported.

2. Read the authoritative Omarchy manual before making changes

The README says the authoritative manual lives in the repository’s `manual/` directory and is mirrored at:

• <https://learn.omacom.io/2/the-omarchy-manual>

The project homepage is:

• <https://omarchy.org>

Use those first-party locations to look for the current installation requirements and the complete contents of **Mac support**, **Omarchy on...**, and **Dual Boot Install**. Confirm that they explicitly name Apple silicon and describe your intended setup. A generic reference to “Mac” should not be assumed to cover an M-series Mac running Tahoe.

This is a reading and compatibility-check step, not authorization to combine unrelated snippets. Follow an installation route only if the current first-party manual provides the complete route, prerequisites, supported hardware, and recovery guidance.

3. Decide what you actually want

If your goal is simply to use Claude Code on macOS, this repository is not documented as the macOS installer for it. Omarchy’s code only shows that its own Linux provisioning process includes Claude among many tools. Obtain Claude Code’s macOS installation instructions from Anthropic’s first-party documentation instead; no Anthropic installation command was supplied here, so none is reproduced in this guide.

If your goal is the entire Omarchy desktop, you need an explicitly supported Linux environment. The supplied files do not establish whether that means separate hardware, a virtual machine, or another route on Apple silicon. Do not select a method by guesswork.

4. Stop if the manual does not explicitly support your case

If the current first-party manual does not clearly cover macOS Tahoe on your Apple-silicon model, the safe conclusion is that installation is unsupported or at least undocumented for your setup. Ask the project through its public GitHub issue or discussion facilities, which the repository metadata says are enabled, before changing disks or boot configuration.

What installation would provide—if you use a supported environment

The supplied documentation describes a full desktop rather than a single utility. Hyprland starts one long-running Quickshell process called `omarchy-shell`. The bar, menus, panels, overlays, notifications, lock screen, Polkit agent, and background picker run as plugins inside that process. User state is stored in `~/.config/omarchy/shell.json`, while user-installed plugins live under `~/.config/omarchy/plugins/`.

Claude-related functionality is optional presentation and monitoring. The agents widget hides itself when no agent usage exists. Its records live under `~/.local/state/omarchy/agents/usage/`. Claude limits require a signed-in CLI; without credentials, the panel reports the authentication problem and falls back to local statistics. A non-default Claude directory can be selected through `CLAUDE_CONFIG_DIR`.

These details explain the end state, but they are not installation steps for macOS.

Documented post-install checks and controls

The following commands are copied from the supplied first-party documentation. **Run them only inside an already installed, supported Omarchy Linux session—not in macOS Terminal.** They do not install Omarchy.

Check whether the Omarchy shell’s IPC endpoint is responding:

omarchy-shell shell ping

List discovered shell plugins:

omarchy-shell shell listPlugins

Disable the agents usage widget if you do not want it shown:

omarchy plugin disable omarchy.agents

Set its refresh interval to 300 seconds:

omarchy bar set omarchy.agents refreshIntervalSec 300 --json

The supplied plugin documentation warns that third-party Omarchy plugins execute as unsandboxed code inside `omarchy-shell`. Installed plugins initially remain disabled for review, and updates show a diff. Only add a plugin repository whose code you are willing to run. This warning concerns Omarchy shell plugins; it does not turn this repository into a Claude Code plugin.

Final installation status

For **macOS Tahoe on Apple silicon**, the installation result from the supplied evidence is:

• Native macOS installation: **not documented**.
• Apple-silicon boot support: **not established**.
• Virtual-machine procedure: **not supplied**.
• Dual-boot procedure: **referenced but not supplied**.
• Safe copy-paste installation command: **none available in the supplied first-party files**.
• Claude Code relationship: **Omarchy runs alongside it by installing and monitoring the Claude CLI within Omarchy; no Claude Code extension is evidenced**.

Do not substitute undocumented commands for the missing procedure. Preserve your Mac installation, consult the complete current first-party manual, and proceed only when it explicitly supports your hardware and chosen deployment method.