7eb818e37b
Choosing Hermes as the default agent built it through mise: a pipx environment with no checkout, so `hermes update` had nothing to move, and the only Hermes that could update itself was the one Hermes Desktop set up. Both paths now run the same setup. omarchy-install-hermes-cli installs the hermes-desktop package and runs upstream's installer from it, pinned to the packaged release and started on main, exactly as Install > AI did; omarchy-install-ai-hermes is that plus opening the app. The terminal, the default agent and the app share one runtime, and it updates itself. --check answers whether --now has anything left to do, not merely whether a hermes runs: choosing Hermes from the menu asks first and opens a terminal only on a no, so a yes has to mean no minutes-long step would run where nobody can see it. With the app installed that means the runtime's own command, its completion marker and the seeded packaged app; a finished runtime whose command is gone, somebody else's, or its own but unable to run gets it back from upstream's path stage without bootstrapping again. Either way the command has to be the one PATH finds, because omarchy-agent runs bare `hermes` and Omarchy puts mise's shims ahead of ~/.local/bin; a command in the way is named rather than installed over. The modes are named outright because the app's launcher used to call this command with no arguments to reconcile a mise copy; a default of --now would turn every launch into an install. --check still refuses to run the retired wrapper, since running it built Hermes through mise, and a machine whose migration is pending can still have it on PATH. Provisioning no longer writes the wrapper, Remove Preinstalls no longer looks for it, and the wrapper, the environment it built and what proves them Omarchy's are known to the installer alone: --retire-mise is the migration's whole job, and --now runs the same removal once the runtime installer has saved the wrapper aside, so a user who chose Hermes before their migration ran is not left with mise's shim answering `hermes`. Only the wrapper proves the environment is Omarchy's, at its path or in that saved copy, so the environment goes first and the wrapper last, judged by mise neither having it installed nor still requesting it; a removal that leaves either behind, or a listing that cannot be read, mise missing included, stops with the commands to finish by hand and leaves the migration pending. The migration that once installed the wrapper is kept as a no-op for late updaters, and one whose default agent was Hermes is told to choose it again. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Co-Authored-By: Codex XHigh <noreply@openai.com>
9.3 KiB
AI
Omarchy treats AI coding agents as first-class citizens, but it doesn't pick a favorite for you. Instead, every major coding-agent CLI comes pre-wired as a lazy-loaded launcher. The launchers are tiny mise-managed stubs in ~/.local/bin/, so nothing is downloaded until the first time you actually run one. Hermes is the exception: nothing is stubbed for it, and choosing it installs it, as Desktop apps below explains. Invoke any of these and authenticate when prompted:
| Command | Agent |
|---|---|
claude |
Claude Code |
codex |
OpenAI Codex |
opencode |
OpenCode |
agy |
Google Antigravity CLI |
copilot |
GitHub Copilot CLI |
crush |
Crush |
grok |
Grok CLI from xAI |
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.
To wrap an additional CLI the same way, run omarchy-mise-install <package> [command-name]. The stubs are kept current along with everything else mise manages when you run omarchy update (or the mup alias).
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.
Muse Code — Meta's muse — uses a preinstalled mise stub like the other agents. Picking it as the default installs Meta's official launcher through mise's HTTP backend. The launcher verifies and updates the native binary for your machine.
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 grows an agents icon the first time Omarchy finds AI coding usage on the machine (and stays out of the way until then). The panel behind it tracks every subscription in one place: your plan, the percentage used of the 5-hour session and weekly limits (or the remaining prepaid balance), and token usage by day and by model. Claude Code, Codex, and Fireworks are covered out of the box.
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.
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, and the Perplexity desktop app.
Hermes Desktop is the one to know about, because a machine has one Hermes, and once the app is installed it is the app's. Unless a hermes you installed yourself already works, 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 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 updates arrive through Omarchy's package updates, so skip the Control UI's own "Update Gateway" button: it would try to write into the package-managed install and fail. 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 the plugin runtimes OpenClaw downloads for itself; the default keeps 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.