Spencer Bull
5345673988
OpenClaw's desktop experience on Linux is its Control UI, served by the gateway the openclaw package runs, so the Install > AI entry installs the package and a web app launcher that routes through the new omarchy-launch-openclaw: first launch hands off to OpenClaw's own onboarding wizard, later launches start the gateway when needed and open the dashboard's single-use browser handoff URL as an app window. Remove > AI tears the gateway service down through OpenClaw's own gateway uninstall (falling back to systemctl by hand), aborts rather than dropping the package under a gateway that will not stop, and keeps the user's agent in ~/.openclaw. OpenClaw also joins Setup > Defaults > Agent through the same agent_installer seam Hermes carries: its CLI is the pacman package rather than a mise tool, so omarchy-install-openclaw-cli answers --check/--now with pacman, and omarchy-agent runs `openclaw chat`, seeding prompts through --message. The menu mark is a new U+E90C glyph traced from the package's lobster favicon; E90B stays free for the Perplexity mark still in flight on its own branch. The launcher recovers the gateway through `openclaw gateway install --force` (unit not enabled: missing, or an install that died after writing it) or `openclaw gateway start` (enabled but stopped), never `openclaw dashboard --yes`: as of OpenClaw 2026.9.1 that defers to "the owning supervisor" in both cases, and once the gateway is up it copies a one-time browser pairing URL into the clipboard. The dashboard probe is bounded so an app-grid launch cannot hang without a terminal to interrupt it. Removal treats only systemd's own "inactive"/"failed" as a stopped gateway, so an unreachable user manager aborts instead of dropping the package under a live process. All of it verified against a real 2026.9.1 install. Removal also takes down the node-host unit if OpenClaw ever installed one, and asks (default no, only on a terminal) whether ~/.openclaw should go too, with its size: the chats and credentials live there next to hundreds of megabytes of plugin runtimes and cache OpenClaw downloads for itself. Onboarding goes through omarchy-openclaw-onboard rather than bare `openclaw onboard`: as of 2026.9.1 the bare command is the guided flow, which ends by running a foreground gateway and handing off to a browser tab without returning, so the install script never reached the app launch and no service was installed. The helper runs the classic wizard (--flow quickstart --install-daemon --skip-ui) as a background job that keeps the terminal as its stdin, so its prompts render and take input as upstream draws them, and stops it once the gateway answers: upstream leaves the wizard running after its outro (only the TUI branch exits, and the model sign-in holds a socket open). Every quickstart prompt precedes the service install, so that point is safe. A gateway that never comes up after this run applies setup ends the wait as a failure instead of hanging, an already-running OpenClaw is left alone rather than mistaken for this run's success, a gateway answering on the port is only this run's once its process is the unit's own MainPID (an orphan from an earlier run) is not mistaken for the service this run installs, and a signal at the helper takes the wizard down with it.
7.5 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. 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 |
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.
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, and OpenCode 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, Grok Bot for chatting with xAI's models, Hermes Desktop, and OpenClaw.
Hermes Desktop is the one to know about, because there is only ever one Hermes on a machine. The app only runs against a runtime built from its own commit, so it installs one of its own under ~/.hermes on first launch, which takes a few minutes and shows its own progress. From then on that is the Hermes the terminal hermes command and the default agent use too, whichever order you installed them in. Removing the app under Remove > AI takes that runtime with it, and keeps your chats, memories, and the skills Hermes wrote for itself.
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.