omacom/omarchy instruction manual

1. Scope, purpose, and relationship to Claude Code

Omarchy instruction manual

Omarchy is an MIT-licensed, opinionated Linux distribution described by its maintainers as “beautiful, fun & agentic.” The supplied files document its Quickshell desktop host, plugin system, status bar, several first-party plugins, agent-usage display, and selected provisioning behavior. They do **not** supply the 51 linked chapters under `manual/`, so installation, navigation, themes, general hotkeys, updates, networking, troubleshooting, and other linked topics cannot be reproduced safely here. Consult the repository’s `manual/` directory or its documented mirror at <https://learn.omacom.io/2/the-omarchy-manual> for those subjects.

**Claude Code classification:** Omarchy **runs alongside** Claude Code. Mechanisms evidenced here are a **standalone application/operating environment** plus management of an **external CLI**. Provisioning writes an install stub for `claude`; the Agents widget reads Claude usage and limit data; and the icon font contains marks for multiple agents. No supplied file documents a Claude Code plugin, MCP server, hook, skill, or context injection. Therefore Omarchy should not be classified as a Claude Code extension.

The desktop is hosted by one long-running `omarchy-shell` Quickshell instance per Hyprland graphical session. The bar, menus, panels, overlays, and headless services run as plugins inside that process. This shares services, avoids launching a fresh Quickshell process for every panel, and permits user plugins from disk. Do not infer an Omarchy installation command from repository metadata: none is documented in the supplied files.

2. Shell architecture and plugin contract

Hyprland starts the shell with `quickshell -p $OMARCHY_PATH/shell`. `shell.qml` is the entry point; `PluginRegistry.qml` discovers and validates plugins and reads enabled state; `BarWidgetRegistry.qml` provides one registry for built-in and third-party widgets. Use the documented restart helper when a fresh process is needed:

omarchy-restart-shell

Every plugin is rooted at a directory containing `manifest.json`. Supported kinds are: `bar-widget`, a component placed in a bar section; `panel`, a floating persistent or summoned window; `overlay`, a fullscreen surface; `menu`, a summoned menu; `service`, a UI-free singleton; and `bar`, a complete replacement bar. Only one full `bar` is active. An invalid selection falls back to `omarchy.bar`. Services start with the shell; panels, overlays, and menus normally load when summoned. `keepLoaded: true` keeps a summoned plugin mounted.

A source-supported minimal bar-widget manifest is:

{
  "schemaVersion": 1,
  "id": "my.org.cool-clock",
  "name": "Cool clock",
  "version": "1.0.0",
  "author": "You",
  "description": "A clock that does cool things",
  "kinds": ["bar-widget"],
  "entryPoints": { "barWidget": "Widget.qml" },
  "barWidget": {
    "displayName": "Cool clock",
    "category": "Time",
    "allowMultiple": false,
    "defaultSection": "left",
    "defaults": { "format": "HH:mm" },
    "schema": [
      { "key": "format", "type": "string", "label": "Format" }
    ]
  }
}

The complete schema is implemented in `services/PluginRegistry.qml`; only fields shown in supplied documentation should be assumed here.

3. Installing, updating, cloning, and enabling plugins

A third-party plugin is a Git repository whose root contains `manifest.json`. Omarchy clones it to `~/.config/omarchy/plugins/<manifest-id>/`. Bare commands are interactive; arguments make the operation non-interactive, and `--yes` skips prompts. Plugins are unsandboxed code inside the shell, so review them before enabling. The installer itself only clones files, validates the manifest, and changes enabled state over IPC; it does not run plugin code, hooks, or `sudo`.

omarchy plugin add https://github.com/acme/omarchy-weather.git
omarchy plugin update acme.weather
omarchy plugin update
omarchy plugin remove acme.weather

For scripts or agents, the documented non-interactive forms are:

omarchy plugin add https://github.com/acme/omarchy-weather.git --enable --yes
omarchy plugin update --yes

An update fetches, displays a diff in interactive use, and fast-forwards the checkout. Because the installed directory is an ordinary Git checkout, the documentation notes that ref pinning or branch changes are ordinary Git operations there, but gives no specific command.

For a manual install, place the manifest and referenced QML under `~/.config/omarchy/plugins/<plugin-id>/`, then run:

omarchy-shell shell rescanPlugins
omarchy plugin enable <id>

Widgets begin in `barWidget.defaultSection`, or the center if omitted. Move them with `omarchy bar move`. Disable or re-enable plugins with `omarchy plugin disable` and `omarchy plugin enable`; discover IDs with `omarchy plugin list`.

To modify a built-in safely, clone it rather than editing shipped source:

omarchy plugin clone omarchy.clock

The clone receives a username-prefixed ID, preserves widget position/settings, redirects existing callers, reloads automatically when files beneath the user plugin directory change, and falls back to the built-in when the active clone is removed.

4. IPC methods, direct calls, and persisted state

`omarchy-shell` forwards IPC to the already-running shell; it does not start one. Basic documented calls are:

omarchy-shell shell ping
omarchy-shell shell toggle omarchy.menu '{"menu":"root"}'
omarchy-shell shell listPlugins
omarchy-shell shell rescanPlugins

The lower-level health check is:

quickshell ipc -p $OMARCHY_PATH/shell call shell ping

The `shell` target implements: `ping` (returns `ok`); `summon <id> <payloadJson>` (loads and opens a plugin, returning `ok` or `unknown`); `hide <id>`; `toggle <id> <payloadJson>`; `call <id> <method> <arg>` for an already-loaded plugin; `rescanPlugins`; `reloadConfig` (returns `ok`); `setPluginEnabled <id> <enabled>` (returns `ok` or `unknown`); and `listPlugins` (name-sorted JSON). For `setPluginEnabled`, only the exact string `true` enables; `True`, `1`, `yes`, omission, and every other value disable.

User state lives in `~/.config/omarchy/shell.json`; plugin source lives under `~/.config/omarchy/plugins/<id>/`. Without user state, the shipped `config/omarchy/shell.json` is used verbatim. After any customization, the user file is authoritative and defaults are not deep-merged.

Top-level `version` must be `1`; an unknown version causes fallback to defaults. `bar.id` selects the complete bar. Widget instances live in `bar.layout.left`, `center`, or `right`; other plugins live in `plugins[]`; settings are inline on each entry. Third-party enabled state means its ID is present. First-party non-bar plugins are enabled unless included in `disabledPlugins[]`. `allowMultiple: true` permits independent repeated entries. `idle.screensaver` and `idle.lock` are seconds from the start of idleness, not sequential delays.

5. Configuring and using the built-in bar

The bar supports top, bottom, left, and right edges. Drag or hold empty bar space to move it; double-left-click empty center space to toggle transparency; drag widgets to reorder. Script equivalents are `omarchy bar position`, `omarchy bar transparent`, `omarchy bar move`, and `omarchy bar set`. `centerAnchor` pins one center widget exactly at screen center; an empty string centers the entire center group. Vertical bars are 28 px wide and text-heavy widgets switch to compact forms.

Interactive widgets and actions are: menu (left menu, right terminal); workspaces (focus); clock (left calendar, right format, middle timezone); media (left play/pause, middle next, scroll tracks, right popup); indicators (run indicator action); system update (update); tray (hover drawer, right-chevron manage); weather (left forecast, right notification); microphone (left mute, middle audio, scroll input volume); audio (popup/mute/volume); network (Wi-Fi/Ethernet and DNS panel); Tailscale (panel/toggle/refresh); Agents (panel/launch/next subscription); power (panel/toggle percentage); Bluetooth (panel/toggle radio); and monitor (brightness/display panel).

Indicator settings may omit `items` to show all, or use a subset such as `['Dnd', 'Reminder', 'NightLight']`; `alwaysShow: true` keeps inactive items visible. Multiple indicator instances are supported.

A documented bar edit is:

omarchy bar set omarchy.agents refreshIntervalSec 300 --json

Numbers require `--json` or they are stored as strings. First-party bar IDs are namespaced, including `omarchy.clock`, `omarchy.audio`, and `omarchy.network`. Full-bar plugins have no off state: enabling another full bar replaces the current one, while a missing or invalid choice safely restores `omarchy.bar`.

6. Creating command modules, QML modules, and bar widgets

A custom module is an entry under `bar.layout.<section>`. For shell-generated output, set `type` to `command`, provide `exec`, and optionally use `interval`, `tooltip`, and `onClick`. This supplied example polls a user script every five seconds:

{
  "version": 1,
  "bar": {
    "layout": {
      "right": [
        { "id": "omarchy.tray" },
        { "id": "vpn", "type": "command", "exec": "~/.config/omarchy/bar/scripts/vpn-status", "interval": 5, "tooltip": "VPN", "onClick": "nm-connection-editor" },
        { "id": "omarchy.audio" }
      ]
    }
  }
}

The command may print plain text or Waybar-style JSON:

{"text":"󰌆","tooltip":"Work VPN","class":"active"}

For a QML module, add `{ "id": "gpu", "type": "qml" }` and create `~/.config/omarchy/bar/modules/gpu.qml`, or set `source` to another path. Its root should be an `Item` with `implicitWidth` and `implicitHeight`. The bar injects optional `bar`, `moduleName`, and `settings` properties.

Available bar APIs are live theme colors `foreground`, `background`, and `urgent`; `fontFamily`; `position`; boolean `vertical`; `barSize` (26 horizontal, 28 vertical); `run(command)` for detached Bash execution; shared `showTooltip`/`hideTooltip`; and `requestPopout`/`releasePopout` to ensure one popup at a time. The docs require argument quoting with `Util.shellQuote` from `qs.Commons` when using `bar.run`.

A separately distributed widget should instead be a plugin manifest declaring `kinds: ["bar-widget"]` and a bar-widget entry point. Rescan it, enable it, and place it using the documented plugin and bar commands.

7. AI Agents usage panel, collectors, settings, and synchronization

`omarchy.agents` is a read-only bar widget and panel for AI coding subscriptions. It watches JSON records under `~/.local/state/omarchy/agents/usage/`. `omarchy-agent-usage-update` invokes one `omarchy-agent-usage-<agent>` collector per provider; the widget triggers updates on its timer and on refresh. It displays plan or auth errors, rate-limit use and reset times, prepaid balance, the last week by day, and token totals by model with input/output/cache details on hover. It self-hides until an enabled provider has usage. Remove it from the bar with:

omarchy plugin disable omarchy.agents

Claude collection uses Anthropic’s OAuth usage endpoint for five-hour and seven-day limits, plus local Claude transcripts, compatible OpenCode sessions, and fallback statistics files. It requires a signed-in CLI for live limits and honors `CLAUDE_CONFIG_DIR`. Codex uses app-server RPC and local sessions, honoring `CODEX_HOME`. Fireworks uses billing APIs and credentials from environment variables, its auth file, or OpenCode authentication.

Bar actions are left panel, right launch agent, middle next subscription. Panel keys are `h`/`l` switch, `j`/`k` scroll, `r` or Enter refresh, Tab neighboring panel, and Esc close. IPC is documented as `omarchy-shell omarchy.agents <open|close|toggle|refresh|next>`.

Settings include `refreshIntervalSec` (900), `syncMode` (`Off`), `syncDir`, `syncFileName`, and `syncDeviceId`. Example:

omarchy bar set omarchy.agents syncDir '~/Sync/agent-usage'

Provider enablement requires replacing the complete nested object:

omarchy bar set omarchy.agents providers '{
  "claude": { "enabled": true },
  "codex": { "enabled": false },
  "fireworks": { "enabled": true }
}' --json

With sync on, snapshots merge activity across devices but never merge account rate limits; account-scoped statistics use the widest value to avoid double counting.

8. Other first-party surfaces: image picker, menu, authentication, and Tailscale

The image picker is a keep-loaded fullscreen grid used for wallpapers, themes, or any image directory. JSON-speaking callers use:

omarchy-shell shell summon omarchy.image-picker '<jsonPayload>'

Supported payload fields are `imageDirs`, `imageRows`, `selectedImage`, `selectionFile`, `doneFile`, `showLabels`, and `filterable`. A positional `image-selector open` target also exists; its image rows are base64-encoded to preserve tabs and newlines. Callers create temporary selection and completion files, pass their paths, and watch for completion; the picker writes the selected path and touches the done file. Cancel finishes without writing a selection. Colors come only from the central theme.

The Omarchy menu is a `menu` plugin summoned within the shared shell. Defaults come from `default/omarchy/omarchy-menu.jsonc`; user additions come from `~/.config/omarchy/extensions/omarchy-menu.jsonc`. Both are watched for changes. The shell batches evaluation of documented `when:` and `checked:` Bash expressions, then runs the selected `action:` through detached execution. Treat menu files as executable configuration.

The lock screen uses native `WlSessionLock`, separate PAM services for password and enrolled-fingerprint authentication, a blurred wallpaper, and Hyprland-aware corners. The Polkit plugin provides a theme-aware privileged-action dialog inside the shell, replacing the former GNOME Polkit agent.

The Tailscale widget shows status, switches connections, browses peers, copies IP/name/DNS values, and sends Taildrop files. It requires `tailscale` on `PATH`; copy requires `wl-copy`; sending requires Taildrop. Enable and place it with:

omarchy plugin enable omarchy.tailscale
omarchy bar move omarchy.tailscale

Panel keys are arrows or `j`/`k`, Enter/Space activate, `c` IP, `n` name, `d` DNS, `s` send, `t` toggle, `r` refresh, Esc close. Received files go to `~/Downloads`; the documented manual receiver is `omarchy tailscale receive`.

9. Provisioned tools, operational limits, and security guidance

The supplied provisioning files show selected behavior, not a supported manual installation procedure. User provisioning applies theme, Chromium, Git, XCompose, work-tool, hardware-specific, keyring, and mise setup stages. If nonblank install inputs exist, Git setup writes `user.name` and `user.email` globally. Login setup configures SDDM. System configuration covers the theme system, browser policy, lockout limit, lock-screen PAM, power-profile shebang repair, SSH command path and keepalive, Docker, Snapper, locate, services, and firewall. No commands to invoke these scripts directly are documented, so this manual does not recommend doing so.

Mise provisioning writes install stubs for Codex, Claude, Crush, Antigravity CLI, GitHub CLI, Copilot, OpenCode, Playwright, Pi, oh-my-pi, Grok, ghui, hunk, HEY CLI, and Ori, and attempts Hermes CLI setup without allowing failure to abort later provisioning. This establishes tool availability intent, not proof that every tool is downloaded, authenticated, or working.

Security boundaries are important. Third-party QML runs unsandboxed in the long-lived desktop process. Review source and update diffs before enabling it; use `--yes` only for repositories already trusted. Menu actions and command modules execute shell commands. Agent collectors access local transcripts, OAuth or API endpoints, and credential locations. Synchronizing usage snapshots copies activity data into the chosen folder. The Fireworks fallback balance is only an estimate based on configured funding and rated costs; its live balance endpoint is described as permission-gated.

Finally, Agents “all-time” totals differ by provider: Codex reads native sessions touched within 30 days, Fireworks requests 30 days, while Claude covers transcripts still present on disk. UI statistics and synchronization should therefore be treated as operational summaries, not billing or audit records.