guides / updated October 1, 2026

Omarchy for AI Coding: Claude Code, Codex, Cursor and Agent Setup (2026)

How to set up Omarchy 4 for AI coding: built-in agent launchers, Claude Code and Codex, tmux agent layouts, worktrees, notifications, hotkeys and the gotchas to know.

Verified against Omarchy 4.0.4 (Sept 2026), checked against the official manual and the omacom/omarchy source on October 1, 2026. Spot something out of date? Tell us.

TL;DR: Omarchy 4 ("Quattro") is the most agent-ready Linux desktop you can install today. It ships lazy launchers for ten coding agents, a one-key agent window, tmux layouts built for running several agents at once, and a top-bar panel for your plan limits. This guide covers what's already there, what to install, and the auto-approve defaults you should know about before you let an agent loose.

What Omarchy is (in one paragraph)

Omarchy is DHH's opinionated Arch Linux + Hyprland setup, now pitched as "the malleable OS for the age of agents." Version 4 rewrote the desktop shell in Quickshell, moved Omarchy itself into real Arch packages, and made Foot the default terminal and Neovim the default editor. You install it from an ISO (flash it, boot it, done in a few minutes). Secure Boot has to be off, and because the disk is encrypted by default, type the unlock password on a wired or 2.4 GHz keyboard, not Bluetooth.

The AI stuff that's already installed

This is the part most "install Claude Code on Linux" tutorials miss: on Omarchy 4 you mostly don't install agents, you just run them.

• Lazy agent launchers. claude, codex, opencode, copilot, crush, grok, pi, agy (Google's Antigravity CLI) and a couple more are pre-wired as stubs in ~/.local/bin. Nothing downloads until the first time you type the command. omarchy update keeps them current.
• A default agent. Pick one with omarchy default agent <name> (or Setup > Defaults > Agent in the menu). After that, Super+Shift+Ctrl+A opens it in its own window, and omarchy agent prompt "review this repo" starts it straight into a task. Launches from your home folder land in ~/Work instead.
• Short aliases. a runs your default agent in the current terminal, cx runs Claude Code, cy runs Codex, c runs opencode.
• A usage panel. The agents icon in the top bar shows your 5-hour and weekly limits for Claude Code and Codex. Left-click to check, right-click to launch.
• An Omarchy skill for your agents. It's linked into Claude Code's and Codex's skill folders so an agent can tweak your desktop config. The manual calls it experimental: use plan mode first.

Read this before you type cx: the aliases and the one-key launcher start agents in auto-approve modes (Claude Code in auto permission mode, Codex with auto-approval; Cursor's CLI, Copilot and Crush get even looser flags). The manual's own warning is that agents launched this way "run unattended." That's the point, and it's also how every story in our Agent Fail Hall of Fame starts. Only run them inside a project folder or a git worktree, never at the root of your home directory.

Installing the rest

Everything below was checked against each vendor's official install docs or the Arch package pages.

Two notes. First, don't run sudo pacman -Syu or yay -Syu to update: Omarchy blocks full system upgrades on purpose and wants omarchy update instead, which snapshots first so you can roll back from the boot menu. Installing single packages with pacman -S is fine. Second, if an agent decides to "update the system" for you, it will hit that same block. Good.

Hotkeys worth learning first

From the Omarchy manual's hotkey page. Super+K shows the full list any time.

10 tips for coding with agents on Omarchy

1. Give each job a workspace. Workspace 1 for agents, 2 for your editor, 3 for the browser and docs. When an agent starts a long run, park it with Super+Shift+Alt+1 and keep working.
2. Use the built-in tmux layouts. tdl cx opens Neovim, Claude Code and a shell side by side. tdl cx cy adds Codex as a second agent. tds gives you editor, a live diff watcher, shell and opencode in one window.
3. One worktree per agent. ga <branch> creates a git worktree and branch and drops you into it; gd removes it. Pair it with tsl 4 cx (four Claude Code panes in a grid) and every agent gets its own copy of the repo instead of fighting over one.
4. Keep a scratchpad agent. Send an agent terminal to the scratchpad with Super+Alt+S, then pop it over whatever you're doing with Super+S for quick questions.
5. Screenshots straight into the agent. Print Screen copies a region to the clipboard; paste it into Claude Code or Codex with Ctrl+V (the agents read images from Ctrl+V, text from Super+V). The screenshot editor can redact before you paste.
6. Turn error dialogs into text. Super+Ctrl+PrtSc OCRs a screen region, which beats retyping a stack trace from a popup.
7. Talk to it. Install > AI > Dictation adds Voxtype: hold F9 to dictate a prompt.
8. Get pinged when the agent needs you. Claude Code supports a Notification hook; point it at notify-send in ~/.claude/settings.json and Omarchy's notification center will tell you when it's waiting. Codex has a notify setting in ~/.codex/config.toml that fires when a turn finishes.
9. Keep keys out of your dotfiles. Put API keys as session environment files in ~/.config/uwsm/env.d/, which sits outside ~/.config/hypr, so you can publish your Hyprland config without leaking anything. Better still, sign in to the agents with your subscription (OAuth) instead of exporting API keys at all.
10. Let the agent rice your desktop, carefully. Asking an agent to change your Hyprland config works well with the bundled Omarchy skill. If it goes sideways, omarchy reinstall configs puts the defaults back.

Gotchas

• Docker needs sudo by default. An agent that runs docker will stall on a password prompt. Sudoless Docker is an opt-in under Setup, with the usual security trade-off.
• Nvidia. The installer chooses the right driver for your GPU generation and enables early KMS. On hybrid laptops where the Nvidia card doesn't drive the display, Omarchy deliberately skips some Nvidia video variables, so don't copy those into your config from old forum posts.
• Screen sharing. Native Wayland apps share fine through PipeWire. Apps running under XWayland (Discord is the usual one) can only see other XWayland windows; the Hyprland wiki's fix is xwaylandvideobridge.
• Password managers in web apps. Omarchy's web-app wrappers don't play well with 1Password, so log in through the regular browser first.
• Installing on top of an existing Arch box. Version 4 is designed to be installed from the ISO. The old curl-script install for vanilla Arch is documented for Omarchy 3; we couldn't confirm it's supported for 4.

From the terminal

Omarchy hands you a one-key, auto-approving agent on a fresh install. We respect the commitment. If that's your setup, you've earned the --dangerously-skip-permissions tee. Keep backups anyway.

Sources: omarchy.org · Omarchy manual · Omarchy source and releases · Claude Code setup · Claude Code hooks · Codex CLI · Arch: openai-codex · Arch: gemini-cli · Arch: opencode · Arch: ollama · Cursor CLI install · VS Code on Linux

Written by Accept All, merch for people who ship with AI. More: guides & trackers · Vibe Log.