Skip to content
Chapters
  1. Welcome to Omarchy!
  2. Getting Started
  3. Coming From Mac or Windows
  4. Navigation
  5. The Top Bar
  6. Themes
  7. Hotkeys
  8. Unified Clipboard & History
  9. Reminders
  10. Notices
  11. Text Extraction & Dictation
  12. Screenshots & Recording
  13. Toggles, Idle & the Screensaver
  14. Omarchy CLI
  15. Terminal
  16. Neovim
  17. AI
  18. Development Tools
  19. Shell Tools
  20. Shell Functions
  21. TUIs
  22. GUIs
  23. Browsers
  24. Commercial apps/services
  25. Web Apps
  26. Gaming
  27. Filling out PDFs
  28. Windows VM
  29. Other Packages
  30. Updates
  31. Dotfiles
  32. Shell Plugins
  33. Monitors
  34. Keyboard, Mouse, Trackpad
  35. Networking
  36. System sleep
  37. Hardware authentication
  38. Fonts
  39. Backgrounds
  40. Prompt
  41. Branding
  42. Common tweaks
  43. Making your own theme
  44. Mac support
  45. Troubleshooting
  46. FAQ
  47. System snapshots
  48. Security
  49. Omarchy on...
  50. Dual Boot Install
  51. Unattended Installs

Manual

AI

Omarchy includes launchers for the coding agents below without choosing a default for you. Run a command to install its CLI on first use, then authenticate when prompted. Hermes is the exception: nothing is installed for it on first use, and choosing it installs Hermes Desktop, as Desktop apps below explains.

Command Agent
claude Claude Code
codex OpenAI Codex
opencode OpenCode
agy Google Antigravity CLI
copilot GitHub Copilot CLI
crush Crush
grok Grok Build from xAI
kimi Kimi Code
pi Mario Zechner’s Pi
omp Oh My Pi
ori Ori, OpenRouter’s harness
hermes Hermes, Nous Research’s agent
muse Muse Code, Meta’s coding agent
cursor-agent Cursor CLI

ori is the odd one out: it runs the other harnesses against OpenRouter’s whole model catalog, so ori claude, ori codex, or ori opencode start those agents on whichever model you point them at, and ori code is Ori’s own agent.

Installing and updating agents

Except for Hermes, these agents use mise’s lazy installation: the first launch installs the CLI, and later launches reuse it. mise also checks an installed agent for a new release at most once every four hours, just before it starts or in the background at a shell prompt. If that update fails or you’re offline, the installed version runs. omarchy update updates installed agents with the rest of Omarchy, and mup updates mise-managed tools only.

An agent’s own updater, such as claude update, codex update, or an update button in an app, does not update the mise-managed install. codex update fails, and claude update can report success while installing a separate copy that mise does not track. If you would rather use an agent’s native installer and updater, add it to disable_tools; see Preinstalled CLI tools.

To install all configured lazy tools before you need them, run mise install --include-lazy. This includes Omarchy’s other default CLI tools as well as the agents. See Preinstalled CLI tools for installing a single tool or using your own installation.

grok is installed through mise’s first-party grok package, the same way as claude and codex. Run grok, or pick it under Setup > Defaults > Agent. Skip the curl | bash installer on x.ai. That path puts a second copy in ~/.grok/bin, prepends it on PATH, and overwrites Omarchy’s wrapper.

The default agent

Pick your default agent with omarchy default agent <name> or under Setup > Defaults > Agent in the Omarchy Menu (Super + Space). If the agent isn’t installed yet, picking it installs it first. A fresh Omarchy will invite you to make this choice with a one-time notification.

Choosing Claude also attempts to set up its browser extension for Chromium, Chrome, Brave, Brave Origin, and Edge. The extension setup applies to all users and may ask for your system password; cancelling or a failed extension install still selects and launches Claude. Restart your browser, enable the extension if prompted, and sign in to Claude to finish connecting it. Run /chrome in Claude to check the connection. Firefox and Zen do not support this extension. If Claude was already your default before this setup was added, select it again to install the extension.

Once you’ve chosen, Super + Shift + Ctrl + A launches the default agent in a dedicated terminal window (or brings up the picker if you haven’t chosen yet). You can also launch it straight into a task with omarchy agent prompt "Review this project". Agents launched this way run unattended in their respective don’t-stop-to-ask modes, so be ready for them to actually do things! And since agents refuse to remember trust for your home directory, launches from $HOME start in ~/Work instead.

There are terminal shortcuts too: a runs the default agent inline in the current terminal, while c, cx, and cy start OpenCode, Claude Code, and Codex directly (again in their auto-approving modes). Theme changes sync to the agents as well: Claude Code, Pi, OpenCode, and Hermes (once Omarchy has installed it) all follow along when you switch the Omarchy theme.

The agents panel

The top bar has an agents icon. Before you’ve set up an agent, its panel walks you through signing in to Claude, Codex, or Grok, and the first one becomes your default agent. After that, the panel puts every subscription on one page: each agent and account with its plan, a meter for each of its 5-hour session and weekly limits with the time until it resets (hover for the exact percentage), or the remaining prepaid balance, under a line that rotates through what you’ve used across all of them, like tokens this week and your most used model. Under Make something it offers starter prompts for a new theme, plugin, or app that hand the task to your default agent. Apps are built the way Omarchy’s own Hype, Monologue, and Omacut are, in C++ and Qt Quick, following the omarchy-app agent skill, and the compiler and Qt pieces they need come installed. Claude Code, Codex, Grok, Fireworks, and Kimi are covered out of the box. Kimi currently reports account quota limits without local token or prompt statistics.

Left-click the bar icon for the panel, right-click to launch your default agent. The usage records behind it are regenerated every 15 minutes by omarchy agent usage-update, and the panel can even merge usage from your other machines via a synced folder. See the README under $OMARCHY_PATH/shell/plugins/agents/ for the full settings.

Several subscriptions

If you pay for more than one Claude, Codex, or Grok plan - a personal Max and a work one, say - Omarchy can keep them all signed in and move between them. Add a subscription with the + in the agents panel, which walks you through it right there, or with omarchy agent account add claude Work (or codex, or grok). It installs the CLI if it’s missing. The first account for a provider signs in through your normal browser, right where the CLI always looks. Every one after that signs in through a private window, so the account your browser is already signed in to doesn’t get picked up by mistake; sign in there as the account you’re adding, and close any private window you already had open first. Never log out of the CLI to do this: logging out revokes the saved sign-in, and that account would have to be added again.

To copy your subscription logins to another Omarchy machine over SSH, run omarchy agent account copy user@laptop. The sender supplies a temporary receiver when the destination does not have one installed, so older Omarchy machines can receive accounts without an update. Installed receivers take precedence. This copies all Claude, Codex, and Grok subscriptions; add provider names to select them, as in omarchy agent account copy laptop claude. Account names and command IDs match the source, including accounts already present on the destination. Unrelated destination accounts receive a numeric suffix if their names conflict, and settings, skills, plugins, and conversation history stay local to each machine.

Existing destination credentials are kept. A source account already signed in there has its name synchronized without replacing its credentials; other accounts are added alongside it. To replace saved credentials for matching accounts, use omarchy agent account copy --replace laptop claude after quitting that account’s sessions on the destination. A fresh destination also gets the source’s active account and switching preferences; an established destination keeps its own.

Credentials travel through SSH and are stored in private files on the destination, so copy only to machines you trust. This is a one-time copy, not ongoing synchronization. Codex refresh tokens can be rotated by another machine, leaving a copied login in need of renewal; separate sign-ins remain the most reliable choice for simultaneous use on several machines. See Codex’s account authentication guidance.

One account per provider is active, and every new session starts as it: cx, cy, a plain claude, codex, or grok, anything launched through omarchy agent, and scripts or editors that find the CLI on PATH. Switch with omarchy agent account use work (and back with omarchy agent account use main), or in the panel by pressing an account’s number and then Enter (or clicking its Use button). Sessions that are already running stay on the account they started with. Conversation history, settings, skills, and plugins are shared across accounts, so claude --continue in the same folder picks up where you left off on the new account.

With more than one account, the panel shows each account’s limits side by side, with the active one marked. By default Omarchy notifies you when the active account passes 95% of a limit, and clicking the notification switches to the account with the most headroom. Hover an account’s line in the panel and click the Autoswitch that appears beside Use (or press m), or run omarchy agent account mode auto, to have it switch on its own instead; while it’s on, Autoswitch takes Use’s place, and clicking it again goes back to notifying. Add a number to change the threshold, as in omarchy agent account mode auto 90. If every account is over the threshold, you’ll hear about it once, along with which account frees up first. While an active account is within 15 points of its threshold (80% at the default), its limits are checked every three minutes rather than every 15.

omarchy agent account list shows every account and its latest limits, omarchy agent account remove work forgets one, and omarchy agent account rename primary Hey renames one (or click an account’s name in the panel). These commands work on your default agent’s accounts; to reach the other provider, name it first, as in omarchy agent account use codex side. The login you already had in ~/.claude or ~/.codex is the Main account and stays where it is. An account left unused for more than about eight hours can show Sign-in required; click it to sign that account in again right in the panel, or start a session in it, which refreshes the sign-in on its own. MCP servers you had when an account was added come along to it, but ones you add later with claude mcp add only reach the account you added them in. Claude Desktop and tools configured with an absolute path to a CLI binary do not follow the switch. An explicit CLAUDE_CONFIG_DIR, CODEX_HOME, or GROK_HOME takes precedence over the selected account.

Crash diagnosis

Omarchy watches systemd-coredump for process crashes. When something segfaults, you’ll get a “Process crashed” notification - click it, and the crash is handed to your default agent along with Omarchy’s diagnose-crash skill, which walks the agent through establishing the facts from the core dump and deciding whether the crash is worth reporting upstream. You can also run it by hand against any PID from coredumpctl list with omarchy agent crash <pid>.

The watching is on by default. Turn it off under Trigger > Toggle > Crash Capture (or with omarchy toggle crash-capture) and the notifications stop; omarchy agent crash <pid> still works by hand.

Crashes can also be silenced one program at a time, which is what the diagnosis offers you at the end. omarchy crash mute hyprland stops the notifications for that program only, omarchy crash mute hyprland off brings them back, and omarchy crash mute on its own lists what you’ve muted. It takes the binary’s path as happily as its name, so omarchy crash mute /usr/bin/hyprland does the same thing. Quote a name with a space in it, as in omarchy crash mute 'Some App'. Everything else still notifies, and the muted program still crashes - this hides the reminder, it doesn’t fix anything.

Desktop apps

The Install > AI menu also carries a few graphical AI apps: the ChatGPT desktop app, the Claude desktop app (Anthropic’s Linux beta, with Chat, Cowork, and Claude Code tabs), Grok Bot for chatting with xAI’s models, Hermes Desktop, OpenClaw, the Perplexity desktop app, and T3 Code. Grok Bot is the desktop chat app. The coding agent is the grok command.

Hermes Desktop is the one to know about, because a machine has one Hermes, and it is the app’s: Hermes is only ever installed through the app, and the hermes command the default agent runs is the app’s. Choosing Hermes as the default agent installs the same thing the Install > AI entry does: the package, and a Hermes runtime under ~/.hermes set up by Hermes’ own installer, which takes a few minutes the first time. That runtime is the one Hermes the terminal hermes command, the default agent and the app all use, and it updates itself with hermes update rather than waiting on an Omarchy release. Installing it also hands Hermes the Omarchy theme as a skin named omarchy, which every Hermes surface follows as you switch themes; pick another under Hermes’ Appearance settings or with /skin if you’d rather it didn’t, and Omarchy leaves that choice alone. Removing the app under Remove > AI closes Hermes first, gateway included, takes that runtime with it, and keeps your chats, memories, and the skills Hermes wrote for itself unless you tell it otherwise: it asks, defaulting to no, whether that data and your connection settings should go too.

OpenClaw’s desktop experience is its Control UI, which opens as a web app backed by its own local gateway. OpenClaw lives in ~/.openclaw and updates itself: use the Control UI’s “Update Gateway” button or run openclaw update, and the gateway restarts on the new version. Omarchy only chooses the release a fresh install starts from. Removing OpenClaw under Remove > AI takes the gateway service and the app with it and then asks whether ~/.openclaw should go too, since that holds your chats and credentials alongside OpenClaw itself and the plugin runtimes it downloads; the default keeps it, and installing OpenClaw again picks it back up.

T3 Code runs from its official AppImage release in ~/.local/share/t3code rather than from a package, so it updates itself. Installing it asks whether to start on the Stable or Nightly channel; switch later in T3 Code’s settings. Your threads and settings live in ~/.t3, and removing T3 Code under Remove > AI takes them with it.

Local LLMs

Omarchy recommends two ways of running local LLM models: LM Studio and Ollama. LM Studio provides a GUI interface for finding open-weight models, installing them, and running them. It’s a great way to get going easily. Ollama offers a CLI for doing so similarly. But if you’re new to local models, I’d start with LM Studio. You can install either under Install > AI in the Omarchy Menu.

The Omarchy Skill

Agent skills help AI use specific tools in a specific way, and Omarchy ships with a default skill for tailoring the system. Like tweaking your Hyprland config, adjusting the bar, or even creating a new theme from scratch. It’s symlinked into the skill directories for Claude Code (~/.claude/skills), Codex (~/.codex/skills), Pi (~/.pi/agent/skills), Antigravity (~/.gemini/config/skills), Hermes (~/.hermes/skills and each ~/.hermes/profiles/*/skills), and the generic ~/.agents/skills location, so most harnesses pick it up automatically.

But you should treat this skill as experimental. Different models will use it to different effect. It’s best to run in plan mode first, so you have an idea of what the agent would like to change. And then be ready to rollback changes or even invoking omarchy reinstall configs, if the agent makes a mess of everything.