T36 passed after two codex rounds

Integration only.

.github/ISSUE_TEMPLATE/config.yml

@@ -1,7 +1,7 @@
 blank_issues_enabled: false
 contact_links:
   - name: Suggestion
-    url: https://github.com/basecamp/omarchy/discussions/categories/suggestions
+    url: https://github.com/omacom/omarchy/discussions/categories/suggestions
     about: Suggest a new feature, change to existing feature, or other ideas in Discussions.
   - name: Support
     url: https://omarchy.org/discord

.github/SECURITY.md

@@ -0,0 +1,47 @@
+# Security at Omarchy
+
+## Report a vulnerability
+
+If you believe you’ve found a security vulnerability in Omarchy, please tell the [Omarchy Security Team](https://omarchy.org/teams/#security) privately so we have an opportunity to investigate and fix it before it is made public.
+
+[security@omarchy.org](mailto:security@omarchy.org?subject=Security%20report)
+
+Please don’t report potential vulnerabilities publicly in GitHub Issues, Discord, or social media before they’ve been resolved.
+
+## What is a vulnerability?
+
+We consider a bug a security vulnerability when it can be exploited to cross a meaningful security boundary: an untrusted or lower-privileged party gains access, permissions, or control they didn’t already have.
+
+Code that could be more robust but does not cross a security boundary is an improvement rather than a security vulnerability. We may still merge a proposed fix and credit the reporter in our release notes.
+
+Eligibility for our [security credits](https://omarchy.org/security/credits/) page depends on whether a report identifies a confirmed security vulnerability, not on its severity.
+
+## What to include
+
+Give us enough information to understand and reproduce the issue:
+
+- The affected component and Omarchy version.
+- An explanation of what an attacker can do before and after exploitation.
+- Steps to reproduce the issue and any proof of concept.
+- Your preferred contact details for follow-up.
+
+## Responsible disclosure
+
+Please act in good faith while investigating and reporting vulnerabilities:
+
+- Only test systems and accounts you own or have explicit permission to test.
+- Avoid privacy violations, disruption, data destruction, and service degradation.
+- Don’t exploit a vulnerability beyond what is needed to demonstrate it.
+- Give us a reasonable opportunity to investigate and address the issue before publishing details.
+
+We’ll review your report and keep you informed as we’re able while we work toward a resolution.
+
+## Credits
+
+Researchers who privately report a confirmed security vulnerability and give us the chance to ship a fix are thanked on the [security credits](https://omarchy.org/security/credits/) page. Accepted improvements that don’t cross a security boundary may still be credited in our release notes.
+
+Credits link to each reporter’s X profile and show their avatar. For duplicate reports, only the first reporter is eligible for credit.
+
+## Regular bugs and support
+
+For anything that isn’t a security vulnerability, please use the [Omarchy issue tracker](https://github.com/omacom/omarchy/issues).

.gitignore

@@ -0,0 +1,6 @@
+
+# Python bytecode (orchestrator)
+__pycache__/
+*.pyc
+
+.claude/

.luarc.json

@@ -0,0 +1,11 @@
+{
+  "workspace": {
+    "library": [
+      "/usr/share/hypr/stubs"
+    ],
+    "checkThirdParty": false
+  },
+  "diagnostics": {
+    "globals": ["hl"]
+  }
+}

AGENTS.md

@@ -1,17 +1,48 @@
+# Task Guides
+
+Deeper instructions for specific kinds of work live in `agents/skills/`. Read the
+matching guide before starting:
+
+- [`agents/skills/command-metadata.md`](agents/skills/command-metadata.md) - adding or changing commands in `bin/`
+- [`agents/skills/install-scripts.md`](agents/skills/install-scripts.md) - working under `install/` or on system/user setup commands
+- [`agents/skills/shell-dev.md`](agents/skills/shell-dev.md) - editing the Quickshell desktop under `shell/`
+- [`agents/skills/icon-font.md`](agents/skills/icon-font.md) - adding branded glyphs to `default/fonts/omarchy/omarchy.ttf`
+- [`agents/skills/acceptance-tests.md`](agents/skills/acceptance-tests.md) - writing or running graphical acceptance tests under `test/acceptance.d/`
+- [`agents/skills/visual-verification.md`](agents/skills/visual-verification.md) - verifying any change with a visual effect in the running UI
+- [`agents/skills/migrations.md`](agents/skills/migrations.md) - creating or changing migrations under `migrations/`
+
+# Documentation Layout
+
+Three documentation trees, split by genre and audience:
+
+- `agents/skills/` - task procedure ("do this when doing X"), for anyone working on the codebase
+- `docs/` - reference on how the system is shaped (file layout, update pipeline, theming, shell architecture), for anyone working on the codebase; skills link here for depth
+- `manual/` - end-user documentation for using Omarchy, published; never codebase internals
+
 # Style
 
+- In markdown documents (`plans/`, `docs/`, `manual/`), write full lines — no hard wrapping at 80 columns; break only at structural boundaries like headings and list items
 - Two spaces for indentation, no tabs
 - Use bash 5 conditionals: use `[[ ]]` for string/file tests and `(( ))` for numeric tests
 - In `[[ ]]`, don't quote variables, but do quote string literals when comparing values (e.g., `[[ $branch == "dev" ]]`)
 - Prefer `(( ))` over numeric operators inside `[[ ]]` (e.g., `(( count < 50 ))`, not `[[ $count -lt 50 ]]`)
+- Prefer a full `if`/`else` conditional for simple two-path control flow; don't rely on `exec` or `exit` in one branch to make following statements unreachable
 - For strings/paths with spaces, quote them instead of escaping spaces with `\ ` (e.g., `"$APP_DIR/Disk Usage.desktop"`, not `$APP_DIR/Disk\ Usage.desktop`)
-- Shebangs must use `#!/bin/bash` consistently (never `#!/usr/bin/env bash`)
+- Shebangs must use `#!/bin/bash` consistently (never `#!/usr/bin/env bash`). A security-sensitive entrypoint may use the exact `#!/bin/bash -p` form only when it must suppress `BASH_ENV` and exported-function startup injection before its first command; that exception must be explained at the boundary and covered by a regression that rejects an ordinary Bash launch with a decoy `-p` argument.
+- Scripts under `install/` and `migrations/` may be sourced and intentionally omit shebangs
 
 # Command Naming
 
-All commands start with `omarchy-`. Prefixes indicate purpose:
+All commands start with `omarchy-`. Prefixes indicate purpose.
+
+The authoritative list of user-facing command groups lives in `bin/omarchy` in `GROUP_DESCRIPTIONS`. Keep `GROUP_DESCRIPTIONS` updated when adding a new command prefix users are meant to browse to.
+
+A group whose commands are all `# omarchy:hidden=true` gets no entry. That table drives the top-level group listing on its own, so an entry there advertises the group even when every command in it is hidden. `apply-` and `provision-` are deliberately absent for that reason; both still route, and `omarchy <group>` still prints a group header without one.
+
+Common prefixes include:
 
 - `cmd-` - check if commands exist, misc utility commands
+- `capture-` - screenshots, screen recordings, and other capture tools
 - `pkg-` - package management helpers
 - `hw-` - hardware detection (return exit codes for use in conditionals)
 - `refresh-` - copy default config to user's `~/.config/`
@@ -23,45 +54,121 @@ All commands start with `omarchy-`. Prefixes indicate purpose:
 - `theme-` - theme management
 - `update-` - update components
 
+Do not maintain a second exhaustive prefix list here. Consult
+`GROUP_DESCRIPTIONS` when selecting or checking a command group so this
+guidance does not drift from the router.
+
+# Runtime Environment
+
+- `$OMARCHY_PATH` is set at the top level by the uwsm session environment and is always available to Omarchy runtime code.
+- Commands in `bin/` and Quickshell QML should rely on `$OMARCHY_PATH` / `Quickshell.env("OMARCHY_PATH")`; do not derive fallback paths from `HOME`, `Quickshell.shellDir`, or re-export/default `OMARCHY_PATH` manually.
+
+# Platforms
+
+Omarchy runs on x86 and aarch64 (ARM). A platform name is the CPU architecture, then a hardware family only when that family needs handling of its own:
+
+- `x86` - every x86_64 machine
+- `aarch64` - every ARM machine without a family of its own (Snapdragon laptops, Raspberry Pis and ARM VMs today)
+- `aarch64-apple` - Apple Silicon Macs
+
+A new family is named `aarch64-<family>` (e.g. `aarch64-qualcomm`, `aarch64-n1x`) and is added only once it needs code of its own, so `aarch64*` always means ARM. `omarchy-hw-platform` prints the most specific name. Use these exact names wherever a platform is named: package lists, pacman template directories, image manifests, dispatch registration, tests and docs. Never introduce `generic`, `arm64`, `apple-silicon` or other spellings; the old `apple-silicon`, `generic-aarch64` and `generic` are read only for compatibility with older image builders.
+
+Ask a helper; don't read `uname -m` or the device tree in feature code:
+
+- `omarchy-hw-x86` / `omarchy-hw-aarch64` - the CPU architecture. Use them for binary and ABI availability: a package with no aarch64 build, an x86 guest VM, multilib.
+- `omarchy-hw-aarch64-apple` (and later `omarchy-hw-aarch64-<family>`) - built on `omarchy-hw-platform`, image-build aware. Use them for hardware behaviour. `omarchy-hw-apple-silicon` is a hidden alias kept for the omarchy-mac packages; don't use it in new code.
+
+Where platform code lives:
+
+- Packages: `install/omarchy-base.packages` for everyone, `install/omarchy-aarch64.packages` for every ARM machine, `install/omarchy-<platform>.packages` for one family, and base packages with no aarch64 build in `install/omarchy-x86_64-only.packages`. `omarchy-pkg-defaults` composes them.
+- Pacman templates: `default/pacman/` for x86, `default/pacman/<platform>/` for each ARM platform.
+- Hardware setup: `install/hardware/<vendor-or-family>/`, gated by a predicate. `install/hardware/apple/` holds Intel Mac quirks; Apple Silicon's own setup ships in the omarchy-mac packages.
+- Boot chains Omarchy can't drive generically: a platform package behind `omarchy-lifecycle-dispatch` ([`docs/lifecycle-dispatch.md`](docs/lifecycle-dispatch.md)). Platforms that boot Limine with UKIs like x86 keep the generic path.
+
+The experience should be the same on every platform. When a package or feature is missing or broken on one, the default is to get it fixed upstream (an aarch64 build, a bug report, a patch to the maintainer) and leave the gap visible meanwhile, not to paper over it. When asked for a platform workaround, say so and propose the upstream fix first. Hiding a menu entry or skipping a package is fine only for things that can't exist there (an x86 guest VM, an x86-only proprietary binary). Alternative packages and platform-only replacements are a last resort, used only when upstream can't or won't fix it, with the reason written next to the code.
+
+# Privileged Commands
+
+- Follow the "Privilege Escalation" section of `default/agents/skills/omarchy/SKILL.md`. It draws the
+  `sudo`/`pkexec` line by whether the caller has a terminal to enter a password in, and the repo's
+  own scripts follow it.
+
+# Git
+
+- Commits should be atomic: include only one coherent change or fix, and do not mix unrelated work.
+- Commit messages should be succinct and describe the change being made.
+
 # Helper Commands
 
 Use these instead of raw shell commands:
 
 - `omarchy-cmd-missing` / `omarchy-cmd-present` - check for commands
-- `omarchy-pkg-missing` / `omarchy-pkg-present` - check for packages
+- `omarchy-pkg-missing` / `omarchy-pkg-present` - check for packages (don't use these if you can just use `omarchy-pkg-add`/`omarchy-pkg-drop`)
-- `omarchy-pkg-add` - install packages (handles both pacman and AUR)
+- `omarchy-pkg-add` - install packages from the configured pacman repos, Omarchy's included; use `omarchy-pkg-aur-add` for AUR packages
+- `omarchy-pkg-drop` - remove packages; use this instead of raw `pacman -R*`
+- `omarchy-notification-send` - send desktop notifications; do not call `notify-send` directly
 - `omarchy-hw-asus-rog` - detect ASUS ROG hardware (and similar `hw-*` commands)
 
+Commands installed by Omarchy's default package set are runtime invariants. Invoke them directly; do not add defensive `omarchy-cmd-present` / `omarchy-cmd-missing` checks around them. Use command-presence helpers only for genuinely optional dependencies or code that can run before the default package set is installed.
+
+Exceptions are allowed for migration and package-helper scripts where the helper may not be available yet, where the helper itself is being implemented, or where direct package-manager behavior is required.
+
+# Background Work
+
+- Long-running code (the shell, daemons, watchers) reacts to events instead of polling with a timer. Polling is the last resort, for state with no change signal; [`agents/skills/shell-dev.md`](agents/skills/shell-dev.md) lists the event sources and the push-refresh pattern.
+
+# Menu
+
+- The menu definition lives in `default/omarchy/omarchy-menu.jsonc`;
+  [`docs/menu.md`](docs/menu.md) covers the schema, guards, and providers.
+- Do not add `aliases` to new menu entries. Aliases are reserved for
+  established alternate names users already type, kept for compatibility.
+
+# Language
+
+- `omarchy-language en|zh` (Setup > Language) owns `LANG` in `/etc/locale.conf`; the installer sets it from its first screen. Nothing in `omarchy update` or migrations may change `/etc/locale.conf`.
+- Chinese menu labels live in `default/omarchy/omarchy-menu.zh-cn.jsonc`, merged when `LANG` starts with `zh_CN`; give a new menu row with translatable words a label there.
+- Shell text goes through `I18n.tr("English %1", arg)` from `qs.Commons`, with its Chinese in `shell/Commons/I18nZh.js` keyed by the English. Notifications and OSD messages are worded by their sender with `omarchy-text "English %1" "$arg"` (Python: `text()`, QML: `I18n.tr`), which reads the same table; the shell shows them as given, so user text is never translated. `test/shell.d/shell-i18n-test.sh` fails on a missing entry.
+
+# Region
+
+- `/etc/omarchy/region` holds the region the installer derived from the timezone (`cn`); no file means Global. The profile lives in `default/regions/cn/`, its contract in `docs/regions.md`.
+- `install/config/region.sh` links the `cn` developer mirrors into `/etc` and `/.cargo` and refuses to replace a regular file it did not create. It serves both the install (the marker) and `omarchy region cn|global` (`OMARCHY_REGION`), which also records or removes the marker; Global removes only the links it made.
+- `omarchy-region` prints the region (`Global` or `China`) and switches it. Nothing in `omarchy update` or migrations may change the region.
+- China-only menu rows carry `"when":"[[ \"$(omarchy-region)\" == \"China\" ]]"` on every row, not only the submenu, because search checks each row's own guard. User-facing docs: `manual/52-china.md`.
+
 # Config Structure
 
 - `config/` - default configs copied to `~/.config/`
 - `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors
-- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, color0-15)
+- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, red/green/yellow/blue/magenta/cyan and bright_* variants)
+
+# Tests
+
+Run focused automated tests for the area you changed;
+[`docs/testing.md`](docs/testing.md) covers how the suites are shaped. Current
+test entry points:
+
+- `./test/all` - aggregate runner for CLI and shell tests; it intentionally does not run graphical acceptance tests
+- `./test/cli` - CLI routing, command metadata, theme helpers, and safe dispatch coverage
+- `./test/shell` - all Omarchy shell tests under `test/shell.d/`
+
+New Omarchy shell tests should live in `test/shell.d/*-test.sh` so `./test/shell` picks them up automatically. Source `test/shell.d/base-test.sh` for shared root-path discovery, assertions, and Node test helpers.
+
+The graphical acceptance suite runs in a disposable VM, not in the active
+development session; see [`agents/skills/acceptance-tests.md`](agents/skills/acceptance-tests.md).
+
+Visual changes must be verified in the running UI in addition to automated
+tests; follow [`agents/skills/visual-verification.md`](agents/skills/visual-verification.md).
 
 # Refresh Pattern
 
 To copy a default config to user config with automatic backup:
 
 ```bash
-omarchy-refresh-config hypr/hyprlock.conf
+omarchy-refresh-config hypr/hyprland.lua
 ```
 
-This copies `~/.local/share/omarchy/config/hypr/hyprlock.conf` to `~/.config/hypr/hyprlock.conf`.
+This copies `$OMARCHY_PATH/config/hypr/hyprland.lua` to `~/.config/hypr/hyprland.lua`. The argument
-
+is interpolated into both paths and only checked with `[[ -e ]]`, so pass a plain relative path: a
-# Migrations
+name containing `..` resolves and copies, landing outside `~/.config` rather than being rejected.
-
-To create a new migration, run `omarchy-dev-add-migration --no-edit`. This creates a migration file named after the unix timestamp of the last commit.
-
-Migration format:
-- No shebang line
-- Start with an `echo` describing what the migration does
-- Use `$OMARCHY_PATH` to reference the omarchy directory
-
-Example:
-```bash
-echo "Disable fingerprint in hyprlock if fingerprint auth is not configured"
-
-if omarchy-cmd-missing fprintd-list || ! fprintd-list "$USER" 2>/dev/null | grep -q "finger"; then
-  sed -i 's/fingerprint:enabled = .*/fingerprint:enabled = false/' ~/.config/hypr/hyprlock.conf
-fi
-```

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -1,9 +1,78 @@
 # Omarchy
 
-Omarchy is a beautiful, modern & opinionated Linux distribution by DHH.
+Omarchy is a beautiful, fun & agentic Linux distribution by DHH.
 
 Read more at [omarchy.org](https://omarchy.org).
 
+## The Omarchy Manual
+
+The manual lives in [`manual/`](manual/), which is its authoritative source.
+
+- [Welcome to Omarchy!](manual/01-welcome-to-omarchy.md)
+
+**The Basics**
+
+- [Getting Started](manual/02-getting-started.md)
+- [Coming From Mac or Windows](manual/03-coming-from-mac-or-windows.md)
+- [Navigation](manual/04-navigation.md)
+- [The top bar](manual/05-the-top-bar.md)
+- [Themes](manual/06-themes.md)
+- [Hotkeys](manual/07-hotkeys.md)
+- [Unified Clipboard & History](manual/08-unified-clipboard-history.md)
+- [Reminders](manual/09-reminders.md)
+- [Notices](manual/10-notices.md)
+- [Text Extraction & Dictation](manual/11-text-extraction-dictation.md)
+- [Screenshots & Recording](manual/12-screenshots-recording.md)
+- [Toggles, idle & screensaver](manual/13-toggles-idle-screensaver.md)
+- [Omarchy CLI](manual/14-omarchy-cli.md)
+
+**The Applications**
+
+- [Terminal](manual/15-terminal.md)
+- [Neovim](manual/16-neovim.md)
+- [AI](manual/17-ai.md)
+- [Development Tools](manual/18-development-tools.md)
+- [Shell Tools](manual/19-shell-tools.md)
+- [Shell Functions](manual/20-shell-functions.md)
+- [TUIs](manual/21-tuis.md)
+- [GUIs](manual/22-guis.md)
+- [Browsers](manual/23-browsers.md)
+- [Commercial apps/services](manual/24-commercial-apps-services.md)
+- [Web Apps](manual/25-web-apps.md)
+- [Gaming](manual/26-gaming.md)
+- [Filling out PDFs](manual/27-filling-out-pdfs.md)
+- [Windows VM](manual/28-windows-vm.md)
+- [Other Packages](manual/29-other-packages.md)
+
+**Configuration**
+
+- [Updates](manual/30-updates.md)
+- [Dotfiles](manual/31-dotfiles.md)
+- [Shell plugins](manual/32-shell-plugins.md)
+- [Monitors](manual/33-monitors.md)
+- [Keyboard, Mouse, Trackpad](manual/34-keyboard-mouse-trackpad.md)
+- [Networking](manual/35-networking.md)
+- [System sleep](manual/36-system-sleep.md)
+- [Hardware authentication](manual/37-hardware-authentication.md)
+- [Fonts](manual/38-fonts.md)
+- [Backgrounds](manual/39-backgrounds.md)
+- [Prompt](manual/40-prompt.md)
+- [Branding](manual/41-branding.md)
+- [Common tweaks](manual/42-common-tweaks.md)
+- [Making your own theme](manual/43-making-your-own-theme.md)
+
+**The Rest**
+
+- [Mac support](manual/44-mac-support.md)
+- [Troubleshooting](manual/45-troubleshooting.md)
+- [FAQ](manual/46-faq.md)
+- [System snapshots](manual/47-system-snapshots.md)
+- [Security](manual/48-security.md)
+- [Omarchy on...](manual/49-omarchy-on.md)
+- [Dual Boot Install](manual/50-dual-boot-install.md)
+- [Unattended Installs](manual/51-unattended-installs.md)
+- [China](manual/52-china.md)
+
 ## License
 
 Omarchy is released under the [MIT License](https://opensource.org/licenses/MIT).

agents/skills/acceptance-tests.md

@@ -0,0 +1,46 @@
+# Acceptance Tests
+
+Read this before writing or running the graphical acceptance suite under
+`test/acceptance.d/`.
+
+The graphical acceptance suite lives in `test/acceptance` with test files under
+`test/acceptance.d/*-test.sh`. It exercises a real installed Omarchy desktop,
+including session health, shell surfaces, panels, keyboard navigation,
+representative applications, and system setup. Source
+`test/acceptance.d/base-test.sh` for the shared helpers.
+
+Run acceptance tests in a disposable VM through the sibling `omarchy-iso`
+repository, not in the active development session. The suite opens and closes
+applications and temporarily changes desktop configuration.
+
+For acceptance-test-only changes, reuse an installed base and sync the suite:
+
+```bash
+cd ../omarchy-iso
+./bin/omarchy-iso-test release/<iso>.iso --reuse-base --sync-omarchy ../omarchy --no-preview
+```
+
+Use `--sync-all ../omarchy` instead of `--sync-omarchy ../omarchy` when the
+acceptance run must exercise local `bin/`, `config/`, or `shell/` source too.
+Changes to package manifests, installation, finalization, or shipped defaults
+require a fresh ISO built from the local checkouts and a run without
+`--reuse-base`:
+
+```bash
+cd ../omarchy-iso
+./bin/omarchy-iso-make --no-boot-offer --local-source ../omarchy ../omarchy-pkgs
+./bin/omarchy-iso-test release/<generated-iso>.iso --no-preview
+```
+
+Keep unrelated acceptance workflows in separate test files. The runner records
+a failed file and continues with the remaining files, which preserves as much
+diagnostic coverage as possible. Restore modified user state with traps, close
+anything the test opens, and capture every visually distinct state (including
+entered input where relevant) as `success-<step>.png`; failure helpers capture
+`failure-<step>.png`. The ISO harness collects the screenshots and logs under
+its timestamped `test-runs/` directory and opens the screenshots after the run
+unless `--no-preview` is passed.
+
+The ISO harness exercises compositor-level shortcuts with QMP virtual keyboard
+input. In-guest `wtype` is suitable for typing into focused controls, but it
+does not reliably prove that a global Hyprland keybinding works.

agents/skills/command-metadata.md

@@ -0,0 +1,31 @@
+# Command Metadata
+
+Read this before adding or changing commands in `bin/`.
+
+Commands in `bin/` can declare CLI metadata in comments near the top of the
+file. `bin/omarchy` scans the first 80 lines, and tests expect command metadata
+to remain valid.
+
+Supported metadata keys:
+
+- `# omarchy:group=...` - override the command group inferred from the filename
+- `# omarchy:name=...` - override the command name inferred from the filename
+- `# omarchy:summary=...` - short help text
+- `# omarchy:args=...` - usage arguments
+- `# omarchy:examples=...` - examples separated with ` | `
+- `# omarchy:alias=...` / `# omarchy:aliases=...` - alternate routes
+- `# omarchy:hidden=true` - hide from default command listings
+- `# omarchy:requires-sudo=true` - mark commands that require sudo
+
+Only use `omarchy:examples` where there are args that need explaining.
+
+Prefer explicit metadata for user-facing commands. Keep routes consistent with
+the filename unless there is a deliberate alias or compatibility route.
+
+Example:
+
+```bash
+# omarchy:summary=Take a screenshot
+# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy]
+# omarchy:examples=omarchy screenshot | omarchy capture screenshot region
+```

agents/skills/icon-font.md

@@ -0,0 +1,75 @@
+# Omarchy Icon Font
+
+Read this before adding a branded glyph to `default/fonts/omarchy/omarchy.ttf`.
+
+The Omarchy icon font is a small private-use font carrying the marks Nerd
+Fonts does not have: the Omarchy logo and the agent and app brand marks. The
+menu draws one by naming the font on an entry:
+
+```jsonc
+"setup.default.agent.grok": {"icon":"","iconFont":"omarchy","label":"Grok", ...}
+```
+
+Without `iconFont`, an entry's `icon` is drawn in the menu font, so reach for
+this font only when a Nerd Font glyph would misrepresent the thing. A generic
+robot for four different AI apps is the case that justifies a real mark; a
+folder or a microphone is not.
+
+`default/fonts/omarchy/README.md` lists every glyph with the URL its artwork
+came from. Keep that list accurate — it is the only record of provenance.
+
+## Adding a glyph
+
+`omarchy dev font` does the work:
+
+```bash
+omarchy dev font list
+omarchy dev font add ollama https://simpleicons.org/icons/ollama.svg
+```
+
+`add` fetches the SVG, scales it into the same 64..960 box the existing marks
+use so it lands at their optical size, appends it at the next free private-use
+codepoint, and adds a line to the font README. It prints the codepoint and the
+glyph itself.
+
+The source must be a **monochrome SVG with a single `<path>`**, because the
+menu recolors the glyph with the active theme's foreground and selection
+colors. Brand icon sets such as <https://simpleicons.org> publish exactly that
+shape. App favicons usually do not: they are multi-color, carry a container
+tile, or split across several paths. Prefer the official mark when it is
+published as flat monochrome art, and fall back to an icon set's redraw when it
+is not.
+
+Two-tone marks are a trap. Every path becomes solid foreground, so a logo whose
+meaning depends on lighter and darker halves turns into an unreadable blob.
+Pick a source whose silhouette alone reads.
+
+## After adding
+
+The command prints these, and all of them matter:
+
+- Point the menu entry at the new codepoint with `"iconFont":"omarchy"`.
+- Bump the charset range asserted in `test/shell.d/menu-test.sh`; that test
+  pins the font's coverage and fails until it matches.
+- Check the README line the command added, and give it a proper display name
+  with `--label` if the glyph name is not the brand's name.
+
+The font is package-owned: `omarchy-settings` installs it to
+`/usr/share/fonts/omarchy/omarchy.ttf`, so a new glyph reaches the desktop
+through a settings release, not through `omarchy update`. Between the merge and
+that release, a pulled checkout renders the new entry with no icon.
+
+## Verifying
+
+Render the whole font and look at it, which catches inverted contours and
+filled counters that a glyph list cannot show:
+
+```bash
+python3 -c "open('/tmp/row.txt','w').write(' '.join(chr(c) for c in range(0xE900, 0xE910)))"
+magick -background white -fill black -font default/fonts/omarchy/omarchy.ttf \
+  -pointsize 110 label:@/tmp/row.txt /tmp/font-row.png
+```
+
+Then confirm it in the running menu per [`visual-verification.md`](visual-verification.md). Avoid leaving two fonts with the `omarchy` family registered: Qt can use an old copy in `~/.local/share/fonts` even when `fc-match omarchy` reports the packaged font. For a preview, either replace the packaged file in the disposable VM or temporarily exclude it with a `<rejectfont>` rule in `~/.config/fontconfig/conf.d/` before loading the candidate.
+
+Refresh the font cache and restart the shell afterwards — Qt reads the font database at startup, so `omarchy menu refresh` alone will not pick up a changed font. Remove temporary fonts and rules after verification.

agents/skills/install-scripts.md

@@ -0,0 +1,22 @@
+# Install Scripts
+
+Read this before working under `install/` or on the system/user setup commands.
+
+The ISO owns installation orchestration. This repo ships target-side setup
+commands and reusable setup leaves:
+
+- `bin/omarchy-apply-system` runs root-owned system setup during ISO finalization.
+- `bin/omarchy-apply-hardware` runs idempotent hardware-specific setup and is called by `omarchy-apply-system`.
+- `bin/omarchy-finalize-user` runs the per-user runtime finalization (skill symlinks, xdg-user-dirs, mime defaults, `install/user/all.sh`). Shipped user defaults are seeded by `/etc/skel` from `omarchy-settings`, not by this command. `bin/omarchy-reinstall-configs` is the explicit destructive resync of those defaults into an existing user's `$HOME`.
+- leaf scripts under `install/` are sourced by `run_logged $OMARCHY_INSTALL/path/to/script.sh` and intentionally do not have shebangs.
+- avoid `exit` in sourced setup scripts unless intentionally aborting setup.
+- use `$OMARCHY_INSTALL` and `$OMARCHY_PATH` instead of hard-coded Omarchy paths.
+- keep root-scoped hardware setup under `install/hardware/` and orchestrate it through `install/hardware/all.sh`.
+- in an image build every `run_logged` leaf in `install/hardware/all.sh` is queued and runs on the machine's first boot instead (`bin/omarchy-provision-hardware`, see `docs/file-layout.md`), possibly offline, using packages already in the image, and before any user exists; keep those leaves idempotent and put nothing but `run_logged` lines in `all.sh`.
+- gate platform-specific setup on a predicate built on `omarchy-hw-platform` (`omarchy-hw-aarch64-apple`), not on `uname -m`; architecture checks (`omarchy-hw-x86`, `omarchy-hw-aarch64`) are only for ABI, binary availability or a repository's `$arch`. Platform names and where platform code lives are in the Platforms section of `AGENTS.md`.
+- keep every per-user setup leaf under `install/user/` (including `install/user/hardware/` and `install/user/first-run/`) so it is clear what must run for each user.
+- The base install supplies matching kernel headers before hardware setup. DKMS installers should install their driver packages and assume the headers exist.
+- prefer helper commands for package and command checks where available.
+
+Raw `command -v`, `pacman`, and `pacman-key` are acceptable in package-helper
+contexts where direct package-manager behavior is the point of the script.

agents/skills/migrations.md

@@ -0,0 +1,172 @@
+# Omarchy migrations
+
+Read this before creating or changing migrations under `migrations/`.
+
+Omarchy migrations are one-time repair scripts for existing installs. They are
+used when a package update needs to change state that pacman cannot safely own by
+itself.
+
+## Migration model
+
+Migrations live in:
+
+```text
+migrations/*.sh
+```
+
+They run as the current Omarchy user through `omarchy-migrate`, normally during
+`omarchy update`. A migration may touch user/session state (`~/.config`,
+`~/.local`, user systemd, browser/editor prefs, DBus/session state), and may also
+perform machine-wide repairs when needed.
+
+Completion state is per-user:
+
+```text
+~/.local/state/omarchy/migrations/<migration filename>
+```
+
+That means every user gets a chance to run every migration. Migrations run as the
+user; privileged operations should invoke the appropriate helper or privilege
+prompt themselves. Migrations must be idempotent: if one user already applied a
+machine-wide repair, the same migration running for another user should detect
+that and no-op.
+
+## When migrations run
+
+### During `omarchy update`
+
+`omarchy update` is the normal update path. It runs package updates, then:
+
+```bash
+omarchy-migrate
+omarchy-hook post-update
+```
+
+`omarchy-migrate` waits for any active pacman transaction to finish, then runs
+all pending migrations for the current user in the visible update terminal.
+
+### At login
+
+Every graphical login starts `omarchy-migrate-notify.service` after
+`graphical-session.target`. The notifier checks:
+
+```bash
+omarchy-migrate --pending
+```
+
+It stays silent while `omarchy update` holds its lock, since that update applies
+the pending migrations itself.
+
+If that user has pending migrations, it shows a notification that opens a
+terminal for:
+
+```bash
+omarchy-migrate
+```
+
+The notifier never runs migrations silently in the background.
+
+This is what covers users who did not run the update themselves: someone who
+bypassed the pacman guard with `sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman
+-Syu`, and any second user on the machine, whose migration markers are per-user
+and therefore still missing after another user updated.
+
+Login is the only trigger on purpose. Watching the packaged migration directory
+also fires during a normal `omarchy update`, which prompts for migrations that
+`omarchy-migrate` is about to run in the visible update terminal.
+
+### Manually
+
+Users can safely run:
+
+```bash
+omarchy-migrate
+```
+
+at any time. Already-completed migrations are skipped.
+
+## Inspecting pending migrations
+
+Use:
+
+```bash
+omarchy-migrate --pending
+```
+
+Exit behavior:
+
+- `0` — one or more migrations are pending
+- non-zero — no migrations are pending
+
+Output is one pending migration per line:
+
+```text
+1781158082.sh
+```
+
+## Creating a migration
+
+Use the helper:
+
+```bash
+omarchy-dev-add-migration --no-edit
+```
+
+This creates:
+
+```text
+migrations/<unix timestamp>.sh
+```
+
+New migration format:
+
+- File permissions must be `0644` (`-rw-r--r--`). Migration runners execute them
+  with `bash -euo pipefail`, not through executable bits.
+- No shebang line.
+- Start with an `echo` describing what the migration does.
+- Use `$OMARCHY_PATH` to reference the Omarchy directory.
+- Be idempotent. Check existing state before changing it.
+- Migrations are strictly ordered and synchronous. A migration that cannot finish must exit non-zero, remain pending, and stop the queue; never mark later migrations complete against state an earlier migration has not established.
+- Use helper commands such as `omarchy-cmd-present`, `omarchy-cmd-missing`,
+  `omarchy-pkg-add`, `omarchy-pkg-drop`, `omarchy-pkg-present`, and
+  `omarchy-pkg-missing` when appropriate.
+- Never restart the Omarchy shell. `omarchy update` restarts it unconditionally
+  after migrations run, and the login-time shell already runs current code and
+  hot-reloads `shell.json` edits.
+- Raw `pacman`, `command -v`, and direct config edits are acceptable when
+  needed for one-off repair work.
+
+Example:
+
+```bash
+echo "Relink Neovim theme to Omarchy current state"
+
+theme_link="$HOME/.config/nvim/lua/plugins/theme.lua"
+current_relative_target="../../../../.local/state/omarchy/current/theme/neovim.lua"
+
+[[ -L $theme_link ]] || exit 0
+ln -sfn "$current_relative_target" "$theme_link"
+```
+
+## Testing migrations
+
+Run a migration against a temporary home when possible:
+
+```bash
+HOME=$(mktemp -d) bash -euo pipefail migrations/<timestamp>.sh
+```
+
+To rerun a migration locally, remove its marker and run the migrator:
+
+```bash
+rm ~/.local/state/omarchy/migrations/<migration>.sh
+omarchy-migrate
+```
+
+Keep a dedicated test while the migration is still being written or bugfixed, if it calls an Omarchy helper whose interface can still change, or if it is a security-sensitive privileged repair (FIDO2, leftover installer artifacts, udev, sshd). Once a one-shot rewrite has shipped in a tagged release and is frozen, drop the test even when that rewrite used sudo, pacman, or limine-mkinitcpio. Keep the migration itself for late-updaters. Tests of `omarchy-migrate`, the login notifier, and `omarchy-upgrade-to-quattro` stay.
+
+Omarchy 4.0 is upgraded through `bin/omarchy-upgrade-to-quattro`, not through the
+normal migration runner. Do not add compatibility migrations for old installer
+layouts; put pre-4 package-layout transition work in the upgrade command instead.
+
+Clearing a privileged file that a retired installer left on disk is the exception, and belongs in a migration whether or not that installer was part of a package layout transition. The upgrade command only runs on a machine still making the 3 to 4 crossing, so anything put there never reaches an install that crossed already, and it never runs at all for an installer that was retired on its own — while the file the installer wrote is still sitting on those machines. The upgrade command finishes by running `omarchy-migrate` (`run_post_upgrade_migrations`), so one migration reaches every population; a copy in the upgrade command would only be a second copy of the same predicate to keep correct. Such a migration must name the defect it clears and match what the old installer actually produced before deleting it. Leave safe administrator-authored files alone; if one still contains the vulnerable privileged action, preserve it under an inactive name rather than discarding custom content or leaving the action executable. A user config that depends on the same retired compatibility path may be repaired in that migration when doing so eliminates an overlapping migration, but only by matching and replacing the exact legacy path while preserving the rest of the file.

agents/skills/shell-dev.md

@@ -0,0 +1,66 @@
+# Omarchy Shell Development
+
+Read this before editing the Quickshell desktop under `shell/`.
+
+The Quickshell desktop runs as a single long-running process out of
+`shell/`. Hyprland autostart launches it directly with `quickshell -n -p`;
+do not start additional standalone Quickshell instances for individual
+components.
+
+Run `omarchy-restart-shell` after making changes to QML files.
+
+## Plugin contract
+
+- First-party plugins live directly under `shell/plugins/` or one category
+  level deeper, such as `shell/plugins/panels/weather/`. First-party bar-only
+  widgets may use adjacent `*.manifest.json` files. Third-party plugins live
+  at `~/.config/omarchy/plugins/<id>/` with a `manifest.json` at the root.
+- Every plugin manifest declares `schemaVersion`, `id`, `name`, `version`,
+  `kinds`, and `entryPoints`. See
+  [`docs/omarchy-shell.md`](../../docs/omarchy-shell.md) and
+  `shell/services/PluginRegistry.qml` for the current contract; fields such as
+  `activation` are optional.
+- Entry-point QML files are `Item`s (not `ShellRoot`), and accept the shell-injected properties `omarchyPath`, `shell`, `manifest`, and `pluginRegistry` / `barWidgetRegistry` as appropriate. First-party plugins receive the host objects. Third-party plugins receive capability-scoped facades: ordinary plugins may look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state; full-bar plugins additionally receive detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities must be stamped from trusted first-party manifests, and third-party registry views and bar configuration must be detached snapshots rather than shared objects. These facades reduce accidental authority but are not a same-process QML sandbox: a visual bar widget can walk its parent hierarchy to ordinary host objects. Authentication services must therefore remain outside both `ShellRoot._services` and the host QObject tree. Do not expose authentication services through new third-party-facing properties.
+- Panel / overlay / menu plugins must expose `open(payloadJson)` and
+  `close()` lifecycle methods for `shell summon` and `shell hide`.
+
+## Text
+
+Wrap every user-visible string in `I18n.tr()` (`import qs.Commons`) and add its Chinese to `shell/Commons/I18nZh.js`; plain JS models that Node tests load stay English, and their text is wrapped where QML shows it.
+
+## IPC
+
+- `bin/omarchy-shell` is the canonical IPC entry point. It forwards to
+  the running shell and does not start it. Prefer it over re-implementing
+  direct Quickshell socket calls in every CLI.
+- The `shell` IPC target exposes lifecycle and configuration methods including
+  `ping`, `summon`, `hide`, `toggle`, `call`, `rescanPlugins`, `reloadConfig`,
+  `setPluginEnabled`, and `listPlugins`. `shell.qml` also registers
+  `image-selector`, which drives the `omarchy.image-picker` panel.
+- Individual plugins register their own IPC targets, named for the plugin rather
+  than for where they appear: the background switcher registers `background`, and
+  bar widgets register one target each — `omarchy.indicators`,
+  `omarchy.system-update`, `omarchy.clock`. There is no `bar` target.
+
+## Keeping state current without polling
+
+The shell runs all day on battery, and a widget is built once per monitor, so a `Timer` that starts a `Process` costs that process times the number of monitors, every tick, forever. Don't poll for state that only changes through known events. Pick the first of these that fits:
+
+- A native Quickshell service that signals on change: `UPower` and `PowerProfiles` (`Quickshell.Services.UPower`), `Hyprland` and each workspace's `lastIpcObject`, `Pipewire`, `Mpris`, `SystemTray`, `Notifications`.
+- An event stream the shell already runs, such as the Hyprland IPC events or the long-running `pactl subscribe` in `Commons/UntypedInput.qml`. Extend it rather than starting a second one.
+- A file watch: `FileView` with `watchChanges`, or the directory watch in `plugins/bar/Bar.qml`, when the state lives in a file the user can read.
+- A push from the command that changes the state. If only Omarchy commands change it, have them call `omarchy-shell -q <target> refresh` after the change, the way `omarchy-reminder` and `omarchy-sudo-passwordless` do. When the change happens later, without a command running (an expiry, say), schedule the refresh with a transient `systemd-run --user --on-active=…` timer. A root-owned timer cannot reach the user's shell.
+
+Polling is the last resort, kept for state with no change signal at all (a remote API, say). Then gate the timer on the panel being open where you can, pick the longest interval the UI can tolerate, and put the poll in one shared service rather than in a per-monitor widget. Never poll a privileged probe: every `sudo -n` can write to the auth log.
+
+## Editing widget files with glyphs
+
+Widget files in `shell/plugins/bar/widgets/` contain Nerd Font glyphs as raw
+unicode characters. Agent file-editing tools can strip multi-byte codepoints
+in some positions — do **not** rewrite widget files wholesale through those
+tools. For glyph fixes, make a targeted edit with the surrounding context, or
+use a Python script that inserts codepoints via `chr(0xXXXXX)`.
+
+## Palette references
+
+Import `qs.Commons as Commons` and use `Commons.Color` for the palette singleton, including `Connections.target`. Qt 6.12 introduces a `Color` type in `QtQuick` that shadows unqualified palette references. This applies to first-party components and third-party plugin QML alike. Keep the unqualified `qs.Commons` import when the file also uses `Style`, `Util`, or `Border`.

agents/skills/visual-verification.md

@@ -0,0 +1,41 @@
+# Visual Verification
+
+Read this before finishing any change with a visual effect: Omarchy shell
+styling and layout, panels, menus, notifications, desktop appearance,
+animations, transitions, screenshots, and screen recording flows.
+
+Visual changes must be verified in the running UI in addition to automated
+tests. Creating an artifact is not sufficient: inspect it for clipping,
+overlap, incorrect spacing, stale state, focus problems, and visual
+regressions before finishing.
+
+Take a full-screen screenshot without opening the editor:
+
+```bash
+omarchy capture screenshot fullscreen save
+```
+
+The command writes to Omasnap's configured screenshot directory. Use `omarchy screenshot` for the interactive capture flow, which copies the capture and shows a timed preview. Use `omarchy screenshot --editor=overlay` to test annotation before output. Capture reference and candidate states as separate images when changing a layer-shell surface or layout, then compare both.
+
+Record a short full-screen video for animation, transition, timing, capture, or
+screen-recording changes:
+
+```bash
+omarchy screenrecord --fullscreen
+# Exercise the changed behavior.
+omarchy screenrecord --stop-recording
+```
+
+The stop command prints the saved video path in the configured Videos
+directory. Review the recording before finishing, and keep it short and focused
+on the changed behavior.
+
+For interactive UI work, use `wtype` to simulate keyboard input when available.
+Example: start the UI in the background, wait briefly for focus, then run
+`wtype -k Right -k Return` to exercise keyboard selection and confirm the
+resulting command output or state change. Prefer this over manual-only
+verification when a UI returns a selected value or changes a symlink/config.
+
+If a launched UI would otherwise remain open, keep track of its PID and stop it
+after the screenshot or recording; avoid broad process kills unless checking
+with `ps` first.

applications/Basecamp.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=Basecamp
+Exec=omarchy-launch-webapp https://launchpad.37signals.com
+StartupWMClass=chrome-launchpad.37signals.com__-Default
+Terminal=false
+Type=Application
+Icon=basecamp
+StartupNotify=true

applications/Discord.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=Discord
+Exec=omarchy-launch-webapp https://discord.com/channels/@me
+StartupWMClass=chrome-discord.com__channels_@me-Default
+Terminal=false
+Type=Application
+Icon=omarchy-discord
+StartupNotify=true

applications/Google Contacts.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=Google Contacts
+Exec=omarchy-launch-webapp https://contacts.google.com/
+StartupWMClass=chrome-contacts.google.com__-Default
+Terminal=false
+Type=Application
+Icon=google-contacts
+StartupNotify=true

applications/Google Maps.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=Google Maps
+Exec=omarchy-launch-webapp https://maps.google.com
+StartupWMClass=chrome-maps.google.com__-Default
+Terminal=false
+Type=Application
+Icon=google-maps
+StartupNotify=true

applications/Google Messages.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=Google Messages
+Exec=omarchy-launch-webapp https://messages.google.com/web/conversations
+StartupWMClass=chrome-messages.google.com__web_conversations-Default
+Terminal=false
+Type=Application
+Icon=google-messages
+StartupNotify=true

applications/Google Photos.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=Google Photos
+Exec=omarchy-launch-webapp https://photos.google.com/
+StartupWMClass=chrome-photos.google.com__-Default
+Terminal=false
+Type=Application
+Icon=google-photos
+StartupNotify=true

applications/HEY.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=HEY
+Exec=omarchy-webapp-handler-hey %u
+Terminal=false
+Type=Application
+Icon=hey
+StartupNotify=true
+MimeType=x-scheme-handler/mailto

applications/WhatsApp.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=WhatsApp
+Exec=omarchy-launch-webapp https://web.whatsapp.com/
+StartupWMClass=chrome-web.whatsapp.com__-Default
+Terminal=false
+Type=Application
+Icon=whatsapp
+StartupNotify=true

applications/X.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=X
+Exec=omarchy-launch-webapp https://x.com/
+StartupWMClass=chrome-x.com__-Default
+Terminal=false
+Type=Application
+Icon=x
+StartupNotify=true

applications/YouTube.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=YouTube
+Exec=omarchy-launch-webapp https://youtube.com/
+StartupWMClass=chrome-youtube.com__-Default
+Terminal=false
+Type=Application
+Icon=youtube
+StartupNotify=true

applications/Zoom.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=Zoom
+Exec=omarchy-webapp-handler-zoom %u
+Terminal=false
+Type=Application
+Icon=zoom
+StartupNotify=true
+MimeType=x-scheme-handler/zoommtg;x-scheme-handler/zoomus

applications/foot.desktop

@@ -0,0 +1,21 @@
+[Desktop Entry]
+Type=Application
+TryExec=foot
+Exec=foot
+Icon=foot
+Terminal=false
+Categories=System;TerminalEmulator;
+Name=Foot
+GenericName=Terminal
+Comment=A fast, lightweight and minimalistic Wayland terminal emulator
+StartupNotify=true
+StartupWMClass=foot
+Actions=New;
+X-TerminalArgExec=-e
+X-TerminalArgAppId=--app-id=
+X-TerminalArgTitle=--title=
+X-TerminalArgDir=--working-directory=
+
+[Desktop Action New]
+Name=New Terminal
+Exec=foot

applications/hidden/btop.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/bvnc.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/cmake-gui.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/cups.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/dropbox.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/electron34.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/electron36.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/electron37.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/fcitx5-configtool.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/fcitx5-wayland-launcher.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/java-java-openjdk.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/jconsole-java-openjdk.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/jshell-java-openjdk.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/kbd-layout-viewer5.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/kcm_fcitx5.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/kcm_kaccounts.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/kvantummanager.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/limine-snapper-restore.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/org.fcitx.Fcitx5.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/org.fcitx.fcitx5-config-qt.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/org.fcitx.fcitx5-migrator.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/org.fcitx.fcitx5-qt5-gui-wrapper.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/org.fcitx.fcitx5-qt6-gui-wrapper.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/qv4l2.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/qvidcap.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/uuctl.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/wiremix.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/xgps.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/hidden/xgpsspeed.desktop

@@ -1,2 +0,0 @@
-[Desktop Entry]
-Hidden=true

applications/typora.desktop

@@ -1,10 +0,0 @@
-[Desktop Entry]
-Name=Typora
-GenericName=Markdown Editor
-Exec=typora --enable-wayland-ime %U
-Icon=typora
-Type=Application
-StartupNotify=true
-Categories=Office;WordProcessor;
-MimeType=text/markdown;text/x-markdown;
-

bin/omarchy-ac-present

@@ -1,9 +0,0 @@
-#!/bin/bash
-
-# Returns true if AC power is connected.
-
-for ac in /sys/class/power_supply/AC* /sys/class/power_supply/ADP*; do
-  [[ -r $ac/online && $(cat "$ac/online") == "1" ]] && exit 0
-done
-
-exit 1

bin/omarchy-agent

@@ -0,0 +1,168 @@
+#!/bin/bash
+
+# omarchy:summary=Launch the default coding agent in a terminal
+# omarchy:args=[--inline] [--pick]
+# omarchy:examples=omarchy agent | omarchy agent --inline
+
+inline=false
+pick=false
+
+# Flags only. A bare prompt would shadow the subcommands under this group, so
+# prompts go through omarchy-agent-prompt, which passes one here as --prompt.
+while (($#)); do
+  case "$1" in
+    --inline)
+      inline=true
+      shift
+      ;;
+    --pick)
+      pick=true
+      shift
+      ;;
+    --prompt)
+      prompt=${2:?--prompt needs a value}
+      shift 2
+      ;;
+    *)
+      echo "Unexpected argument: $1" >&2
+      echo "To pass a prompt: omarchy agent prompt \"$*\"" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Agents refuse to remember trust for $HOME, so launches from the keybinding or
+# menu start in the work directory instead of re-asking on every session.
+[[ $PWD == "$HOME" && -d $HOME/Work ]] && cd "$HOME/Work"
+
+agent=$(omarchy-default-agent)
+
+# Omarchy ships without a default, so there is nothing to launch until one is
+# picked. --pick offers the choice instead of the error, which is what the
+# keybinding wants: a keypress that opens nothing explains nothing.
+if [[ -z $agent ]]; then
+  [[ $pick == "true" ]] && exec omarchy-menu summon setup.default.agent
+  echo "Choose default agent with: omarchy default agent <name>" >&2
+  exit 1
+fi
+
+if omarchy-cmd-missing "$agent"; then
+  echo "$agent is not installed. Choose an installed agent with: omarchy default agent <name>" >&2
+  exit 1
+fi
+
+# Agents launched from the keybinding or menu run unattended, so each one starts
+# with its own spelling of "don't stop to ask". Pi and Ori have none to skip.
+case "$agent" in
+opencode)
+  command=(opencode --auto)
+  [[ -n ${prompt:-} ]] && command+=(--prompt "$prompt")
+  ;;
+agy)
+  command=(agy --dangerously-skip-permissions)
+  [[ -n ${prompt:-} ]] && command+=(--prompt-interactive "$prompt")
+  ;;
+copilot)
+  command=(copilot --allow-all)
+  [[ -n ${prompt:-} ]] && command+=(--interactive "$prompt")
+  ;;
+crush)
+  # --yolo belongs to the interactive command only; `crush run` never prompts.
+  if [[ -n ${prompt:-} ]]; then
+    command=(crush run "$prompt")
+  else
+    command=(crush --yolo)
+  fi
+  ;;
+claude)
+  command=(claude --permission-mode auto)
+  [[ -n ${prompt:-} ]] && command+=(-- "$prompt")
+  ;;
+grok)
+  command=(grok --permission-mode bypassPermissions)
+  [[ -n ${prompt:-} ]] && command+=(-- "$prompt")
+  ;;
+openclaw)
+  # The launcher owns onboarding and the gateway dance: OpenClaw's terminal UI
+  # must attach to the running gateway (the embedded `openclaw chat` refuses to
+  # start while the gateway owns the state directory). It has no permission
+  # prompts to skip, and --message seeds the session while keeping it
+  # interactive.
+  command=(omarchy-launch-openclaw --tui)
+  [[ -n ${prompt:-} ]] && command+=(--message "$prompt")
+  ;;
+codex)
+  command=(codex --approve-for-me)
+  [[ -n ${prompt:-} ]] && command+=(-- "$prompt")
+  ;;
+cursor-agent)
+  # --yolo covers commands only; the workspace trust dialog has its own flag.
+  # A one-word prompt naming a subcommand (update, login, help) still runs that
+  # subcommand after a bare --, so the agent subcommand is named outright, and
+  # -- after it keeps a prompt starting with a dash from being read as an option.
+  command=(cursor-agent --yolo --trust)
+  [[ -n ${prompt:-} ]] && command+=(agent -- "$prompt")
+  ;;
+hermes)
+  if [[ -n ${prompt:-} ]]; then
+    command=(env -u HERMES_SESSION_SOURCE hermes chat --yolo --tui "--query=$prompt")
+  else
+    command=(hermes --yolo)
+  fi
+  ;;
+muse)
+  # --approval-mode never skips the tool prompts but keeps Muse's own sandbox.
+  command=(muse --approval-mode never)
+  [[ -n ${prompt:-} ]] && command+=(-- "$prompt")
+  ;;
+omp)
+  command=(omp --auto-approve)
+  [[ -n ${prompt:-} ]] && command+=(-- "$prompt")
+  ;;
+ori)
+  # Ori is a harness launcher, and `ori code` is the agent it runs itself.
+  # A prompt alone means one headless turn there, printed after the turn ends,
+  # so --interactive is what seeds the session with it and keeps the window.
+  command=(ori code)
+  [[ -n ${prompt:-} ]] && command+=(--interactive --prompt "$prompt")
+  ;;
+pi)
+  command=(pi)
+  [[ -n ${prompt:-} ]] && command+=("$prompt")
+  ;;
+*)
+  echo "Unsupported default agent: $agent" >&2
+  exit 1
+  ;;
+esac
+
+# A new session uses the current selection rather than its parent's account
+# pin. Explicit provider homes still override the selection. Carry the new pin
+# in the command, since terminals launched through uwsm don't inherit our env.
+case "$agent" in
+claude) home_env="CLAUDE_CONFIG_DIR" ;;
+codex) home_env="CODEX_HOME" ;;
+grok) home_env="GROK_HOME" ;;
+*) home_env="" ;;
+esac
+if [[ -n $home_env ]]; then
+  account_pin="OMARCHY_AGENT_${agent^^}_HOME"
+  if [[ -v $account_pin && ${!home_env:-} == "${!account_pin}" ]]; then
+    unset "$home_env"
+  fi
+  unset "$account_pin"
+  if [[ -z ${!home_env:-} ]]; then
+    home=$(omarchy-agent-account-home "$agent")
+    account_env=(env -u "$home_env" "$account_pin=$home")
+    [[ -n $home ]] && account_env+=("$home_env=$home")
+    command=("${account_env[@]}" "${command[@]}")
+  fi
+fi
+
+if [[ $inline == "true" ]]; then
+  exec "${command[@]}"
+else
+  # A fixed app-id rather than the default org.omarchy.<binary>, so every agent
+  # window shares one class for window rules and themes to single out.
+  exec omarchy-launch-tui --app-id=org.omarchy.agent "${command[@]}"
+fi

bin/omarchy-agent-account-add

@@ -0,0 +1,223 @@
+#!/bin/bash
+
+# omarchy:summary=Sign in to a Claude, Codex, or Grok subscription
+# omarchy:args=[--check] [--events] [--reauth <account>] [claude|codex|grok] [label]
+# omarchy:examples=omarchy agent account add claude | omarchy agent account add Work | omarchy agent account add codex Side
+
+set -uo pipefail
+
+# --check prints, per provider, whether adding one now would be its first
+# sign-in, an additional account, or not possible yet. --events is for the
+# agents panel: progress arrives as `@@omarchy <event> <detail>` lines mixed
+# into the CLI's own output (which carries codes the panel shows), nothing
+# waits on a terminal, and the result also lands as a notification in case
+# the panel has closed.
+# --reauth <account> signs an account that's already here in again, in its
+# own home, for when its sign-in has lapsed.
+check=false
+events=false
+reauth=""
+while [[ ${1:-} == --* ]]; do
+  case "$1" in
+  --check) check=true ;;
+  --events) events=true ;;
+  --reauth)
+    reauth="${2:-}"
+    shift
+    ;;
+  *) break ;;
+  esac
+  shift
+done
+
+# Whether a provider's own home (~/.claude, ~/.codex, ~/.grok) is signed in.
+primary_signed_in() {
+  omarchy-agent-account-state list "$1" | jq -e '.[0].accounts | any(.primary and .signedIn)' >/dev/null
+}
+
+if [[ $check == "true" ]]; then
+  for p in claude codex grok; do
+    if primary_signed_in "$p"; then
+      echo "$p additional"
+    else
+      echo "$p first"
+    fi
+  done
+  exit 0
+fi
+
+# The provider can be left out when it's your default agent:
+# `omarchy agent account add Work`.
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]]; then
+  default=$(omarchy-default-agent)
+  [[ $default == "claude" || $default == "codex" || $default == "grok" ]] && set -- "$default" "$@"
+fi
+
+case "${1:-}" in
+claude) provider="claude"; name="Claude"; site="claude.ai"; package="claude"; home_env="CLAUDE_CONFIG_DIR" ;;
+codex) provider="codex"; name="Codex"; site="chatgpt.com"; package="codex"; home_env="CODEX_HOME" ;;
+grok) provider="grok"; name="Grok"; site="x.ai"; package="grok"; home_env="GROK_HOME" ;;
+*)
+  echo "Usage: omarchy-agent-account-add [--check] [--events] [--reauth <account>] [claude|codex|grok] [label]" >&2
+  exit 1
+  ;;
+esac
+label="${2:-}"
+
+say() {
+  if [[ $events == "true" ]]; then
+    printf '@@omarchy status %s\n' "$*"
+  else
+    echo "$*"
+  fi
+}
+
+finish() {
+  if [[ $events == "true" ]]; then
+    printf '@@omarchy done %s\n' "$1"
+    omarchy-notification-send -g 󰚩 "$1"
+  else
+    echo
+    echo "$1"
+  fi
+}
+
+fail() {
+  if [[ $events == "true" ]]; then
+    printf '@@omarchy error %s\n' "$1"
+    omarchy-notification-send -g 󰚩 -u critical "$(omarchy-text "Couldn't add the %1 account" "$name")" "$1"
+  else
+    echo "$1" >&2
+  fi
+  exit 1
+}
+
+# Cancelling from the panel stops the CLI's login too, and leaves no
+# half-made home behind.
+home=""
+browser=""
+cleanup() {
+  [[ -n $browser ]] && rm -f "$browser"
+  [[ -n $home && -d $home && $home == */.pending/* ]] && rm -rf "$home"
+}
+trap cleanup EXIT
+trap 'pkill -TERM -P $$; exit 130' TERM INT
+
+# Bash holds a trap until a foreground command finishes, and a login waits on
+# the browser for as long as it takes. Running it in the background behind a
+# `wait` lets Cancel stop it at once. It keeps this script's stdin, where the
+# panel sends a pasted code.
+interruptible() {
+  "$@" <&0 &
+  wait $!
+}
+
+if omarchy-cmd-missing "$provider"; then
+  say "$(omarchy-text "Installing the %1 CLI…" "$name")"
+  if [[ $events == "true" ]]; then
+    mise use -g "$package" >/dev/null 2>&1 || fail "$(omarchy-text "Installing the %1 CLI didn't finish." "$name")"
+  else
+    mise use -g "$package" || exit 1
+  fi
+fi
+
+# Your main browser is almost certainly signed in to the account you already
+# have, and a login would quietly reuse it. The CLIs open their login page
+# through $BROWSER, so this points it at a private window instead.
+private_browser() {
+  browser=$(mktemp "${XDG_RUNTIME_DIR:-/tmp}/omarchy-account-browser.XXXXXX")
+  printf '#!/bin/bash\nexec omarchy-launch-browser --private "$1"\n' >"$browser"
+  chmod +x "$browser"
+}
+
+case "$provider" in
+claude) login_command=(claude auth login) ;;
+codex) login_command=(codex login) ;;
+grok) login_command=(grok login) ;;
+esac
+
+# The CLI's own home, whatever this shell has pointed it at.
+login() {
+  interruptible env -u CLAUDE_CONFIG_DIR -u CODEX_HOME -u GROK_HOME "OMARCHY_AGENT_${provider^^}_HOME=" "${login_command[@]}"
+}
+
+# Signing an account that's already here in again, where it lives: the
+# primary home through the normal browser, an added one through a private
+# window. Its home is never recreated or removed.
+if [[ -n $reauth ]]; then
+  if [[ $reauth == ":primary" ]]; then
+    account_home="$HOME/.$provider"
+  else
+    account_home=$(omarchy-agent-account-state homes "$provider" | awk -F'\t' -v id="$reauth" '$1 == id { print $2 }')
+  fi
+  [[ -n $account_home ]] || fail "$(omarchy-text "No %1 account named %2." "$name" "$reauth")"
+
+  if [[ $account_home == "$HOME/.$provider" ]]; then
+    say "$(omarchy-text "Sign in to %1 again in the browser window that opens." "$name")"
+    login || fail "$(omarchy-text "The %1 sign-in didn't finish." "$name")"
+  else
+    say "$(omarchy-text "Sign in again as this account in the private window that opens.")"
+    private_browser
+    interruptible env BROWSER="$browser" "$home_env=$account_home" "${login_command[@]}" || fail "$(omarchy-text "The %1 sign-in didn't finish." "$name")"
+  fi
+
+  omarchy-agent-usage-update --force "$provider" >/dev/null 2>&1 &
+  finish "$(omarchy-text "Signed in to %1 again." "$name")"
+  exit 0
+fi
+
+# The first subscription signs in where the CLI always looks, through your
+# normal browser: nothing is signed in there yet that it could be mistaken for.
+if ! primary_signed_in "$provider"; then
+  say "$(omarchy-text "Sign in to %1 in the browser window that opens." "$name")"
+  if login && primary_signed_in "$provider"; then
+    # The first agent signed in on a machine with none chosen becomes the
+    # default, so `omarchy agent` and the panel's starter prompts have one to
+    # run. A default someone already picked is never touched.
+    if [[ -z $(omarchy-default-agent) ]]; then
+      mkdir -p "$HOME/.config/omarchy/defaults"
+      printf '%s\n' "$provider" >"$HOME/.config/omarchy/defaults/agent"
+    fi
+    omarchy-agent-usage-update --force "$provider" >/dev/null 2>&1 &
+    finish "$(omarchy-text "Signed in to %1." "$name")"
+  else
+    fail "$(omarchy-text "The %1 sign-in didn't finish." "$name")"
+  fi
+else
+  if [[ -z $label && $events == "false" && -t 0 ]]; then
+    label=$(gum input --placeholder "Work" --prompt "Name this $name account: ") || exit 130
+  fi
+
+  if [[ $events == "true" ]]; then
+    say "$(omarchy-text "Sign in as the account you're adding in the private window that opens.")"
+  else
+    cat <<EOF
+
+Sign in as the account you're adding in the private window that opens.
+If a private window was already open, close it first, or $site may reuse whoever it has signed in.
+
+Don't log out of the $name CLI to do this: logging out revokes the saved sign-in.
+
+EOF
+  fi
+
+  home=$(omarchy-agent-account-state begin "$provider") || fail "$(omarchy-text "Couldn't set up a home for the new account.")"
+
+  private_browser
+  interruptible env BROWSER="$browser" "$home_env=$home" "${login_command[@]}"
+
+  if account=$(omarchy-agent-account-state register "$provider" "$label" "$home" 2>&1); then
+    home=""
+    added=$(jq -r '.label + (if .email != "" then " (" + .email + ")" else "" end)' <<<"$account")
+    omarchy-agent-usage-update --force "$provider" >/dev/null 2>&1 &
+    if [[ $events == "true" ]]; then
+      finish "$(omarchy-text "Added %1." "$added")"
+    else
+      finish "$(omarchy-text "Added %1." "$added")"
+      echo "Switch to it with: omarchy agent account use $provider $(jq -r .id <<<"$account")"
+    fi
+  else
+    home=""
+    fail "$account"
+  fi
+fi

bin/omarchy-agent-account-exec

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# omarchy:summary=Run Claude, Codex, or Grok as the selected subscription account
+# omarchy:args=<claude|codex|grok> [args...]
+# omarchy:hidden=true
+
+set -euo pipefail
+
+case "${1:-}" in
+  claude) account_env="CLAUDE_CONFIG_DIR" ;;
+  codex) account_env="CODEX_HOME" ;;
+  grok) account_env="GROK_HOME" ;;
+  *)
+    echo "Usage: omarchy-agent-account-exec <claude|codex|grok> [args...]" >&2
+    exit 1
+    ;;
+esac
+
+provider=$1
+shift
+
+# mise removes its wrapper dispatch directories before calling us, so exec
+# finds the real CLI (or its first-run installer) rather than this wrapper.
+# Pin the resolved home for children, including an implicit Main account.
+# Explicit provider homes still take precedence.
+if [[ -z ${!account_env:-} ]]; then
+  account_home=$(omarchy-agent-account-home "$provider")
+  export "OMARCHY_AGENT_${provider^^}_HOME=$account_home"
+  if [[ -n $account_home ]]; then
+    export "$account_env=$account_home"
+  fi
+fi
+
+# Resolve before restoring dispatch on PATH: mise removes the wrapper paths to
+# avoid recursion, but the agent's subprocesses need them for other providers.
+if ! agent_binary=$(type -P "$provider"); then
+  # A mise dispatcher can exist before its CLI or first-run installer does.
+  export MISE_MINIMUM_RELEASE_AGE=0
+  mise use -g --quiet "$provider"
+  agent_binary=$(mise which "$provider")
+fi
+export PATH="${MISE_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/mise}/command-wrappers/bin:$PATH"
+exec "$agent_binary" "$@"

bin/omarchy-agent-account-home

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# omarchy:summary=Print the config home of the active Claude, Codex, or Grok account
+# omarchy:args=<claude|codex|grok>
+# omarchy:hidden=true
+
+# Prints nothing while the primary account (~/.claude, ~/.codex) is active, so
+# a launch only sets CLAUDE_CONFIG_DIR / CODEX_HOME when there's somewhere
+# else to point it. Without a registry, no Python starts at all: this runs on
+# every `claude` and `codex` typed at a prompt.
+registry="${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/agents/accounts/${1:-}.json"
+
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]]; then
+  echo "Usage: omarchy-agent-account-home <claude|codex|grok>" >&2
+  exit 1
+fi
+
+# A running session pins its home, including an empty value for Main. Claude's
+# implicit default also selects ~/.claude.json, so Main must stay implicit.
+account_pin="OMARCHY_AGENT_${1^^}_HOME"
+if [[ -v $account_pin ]]; then
+  printf '%s' "${!account_pin}"
+elif [[ -f $registry ]]; then
+  exec omarchy-agent-account-state home "$1"
+fi

bin/omarchy-agent-account-list

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+# omarchy:summary=List Claude, Codex, and Grok subscription accounts and their limits
+# omarchy:args=[claude|codex|grok] [--json]
+# omarchy:examples=omarchy agent account list | omarchy agent account list claude --json
+
+set -uo pipefail
+
+provider=""
+json=false
+for arg in "$@"; do
+  case "$arg" in
+  claude | codex | grok) provider="$arg" ;;
+  --json) json=true ;;
+  *)
+    echo "Usage: omarchy-agent-account-list [claude|codex|grok] [--json]" >&2
+    exit 1
+    ;;
+  esac
+done
+
+usage_dir="${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/agents/usage"
+accounts=$(omarchy-agent-account-state list $provider) || exit 1
+
+# Join each account with the limits its provider's usage record last saw. With
+# a single account the collectors keep its limits at the record's top level.
+accounts=$(jq -c --arg dir "$usage_dir" '
+  map(. as $p | .accounts |= map(. + {limits: []}))' <<<"$accounts")
+for p in claude codex grok; do
+  record="$usage_dir/$p.json"
+  [[ -f $record ]] || continue
+  accounts=$(jq -c --arg p "$p" --slurpfile record "$record" '
+    map(if .provider == $p then
+      .accounts |= map(. as $a | . + {limits: (
+        if ($record[0].accounts // []) | length > 0 then
+          [$record[0].accounts[] | select(.id == $a.id) | .limits] | first // []
+        elif $a.primary then
+          $record[0].limits // []
+        else
+          []
+        end)})
+    else . end)' <<<"$accounts")
+done
+
+if [[ $json == "true" ]]; then
+  echo "$accounts"
+else
+  # A provider nobody has signed in to has nothing to list.
+  for (( i = 0; i < $(jq length <<<"$accounts"); i++ )); do
+    jq -e ".[$i].accounts | any(.signedIn)" <<<"$accounts" >/dev/null || continue
+    jq -r ".[$i] | \"\(.name) — \(.switch) switching at \(.threshold)%\"" <<<"$accounts"
+    jq -r ".[$i].accounts[] |
+      \"\(if .active then \"*\" else \" \" end)\t\(.id)\t\(.label)\t\(.plan)\t\(.email)\t\" +
+      ([.limits[]? | select(.percent != null) | \"\(.label): \((.percent * 100) | round)%\"] | join(\", \"))" <<<"$accounts" |
+      column -t -s $'\t' | sed 's/^/  /'
+    echo
+  done
+fi

bin/omarchy-agent-account-mode

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# omarchy:summary=Switch Claude, Codex, or Grok accounts automatically near a limit, or only notify
+# omarchy:args=[claude|codex|grok] [manual|auto] [threshold]
+# omarchy:examples=omarchy agent account mode auto | omarchy agent account mode auto 90 | omarchy agent account mode codex manual
+
+set -uo pipefail
+
+# The provider can be left out when it's your default agent:
+# `omarchy agent account use work`.
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]]; then
+  default=$(omarchy-default-agent)
+  [[ $default == "claude" || $default == "codex" || $default == "grok" ]] && set -- "$default" "$@"
+fi
+
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]]; then
+  echo "Usage: omarchy-agent-account-mode [claude|codex|grok] [manual|auto] [threshold]" >&2
+  exit 1
+fi
+
+if [[ -n ${2:-} ]]; then
+  omarchy-agent-account-state mode "$@" || exit 1
+fi
+
+omarchy-agent-account-state registry "$1" | jq -r '
+  if .switch == "auto" then
+    "\(.name) switches new sessions to the account with the most headroom at \(.threshold)%."
+  else
+    "\(.name) notifies at \(.threshold)% and switches when you say so."
+  end'

bin/omarchy-agent-account-remove

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# omarchy:summary=Forget an added Claude, Codex, or Grok account
+# omarchy:args=[claude|codex|grok] <account>
+# omarchy:examples=omarchy agent account remove work | omarchy agent account remove codex side
+
+set -uo pipefail
+
+# The provider can be left out when it's your default agent:
+# `omarchy agent account use work`.
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]]; then
+  default=$(omarchy-default-agent)
+  [[ $default == "claude" || $default == "codex" || $default == "grok" ]] && set -- "$default" "$@"
+fi
+
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]] || [[ -z ${2:-} ]]; then
+  echo "Usage: omarchy-agent-account-remove [claude|codex|grok] <account>" >&2
+  exit 1
+fi
+
+# Removing only deletes the account's home here. It never logs out, which
+# would revoke the sign-in for every other copy of it too.
+if [[ -t 0 ]] && ! gum confirm "Forget the $1 account $2? You'd have to sign in again to add it back."; then
+  exit 130
+fi
+
+account=$(omarchy-agent-account-state remove "$1" "$2") || exit 1
+echo "Forgot $(jq -r .label <<<"$account")."
+# The panel reads which accounts exist from the usage record.
+omarchy-agent-usage-update --limits-only "$1" >/dev/null 2>&1 &

bin/omarchy-agent-account-rename

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# omarchy:summary=Rename a Claude, Codex, or Grok subscription account
+# omarchy:args=[claude|codex|grok] <account> <name>
+# omarchy:examples=omarchy agent account rename primary Hey | omarchy agent account rename codex side Side project
+
+set -uo pipefail
+
+# The provider can be left out when it's your default agent:
+# `omarchy agent account rename primary Hey`.
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]]; then
+  default=$(omarchy-default-agent)
+  [[ $default == "claude" || $default == "codex" || $default == "grok" ]] && set -- "$default" "$@"
+fi
+
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]] || (( $# < 3 )); then
+  echo "Usage: omarchy-agent-account-rename [claude|codex|grok] <account> <name>" >&2
+  exit 1
+fi
+
+account=$(omarchy-agent-account-state rename "$@") || exit 1
+echo "Renamed to $(jq -r .label <<<"$account"). Switch to it with: omarchy agent account use $(jq -r .id <<<"$account")"
+# The panel reads account names from the usage record.
+omarchy-agent-usage-update --limits-only "$1" >/dev/null 2>&1 &

bin/omarchy-agent-account-state

@@ -0,0 +1,794 @@
+#!/usr/bin/python3
+# omarchy:summary=Read and change the registry of Claude, Codex, and Grok subscription accounts
+# omarchy:args=<registry|home|homes|list|refresh|begin|register|use|rename|remove|mode|link|autoswitch> [provider] [args...]
+# omarchy:hidden=true
+"""The account registry behind `omarchy agent account`.
+
+An account is a Claude Code, Codex, or Grok login Omarchy keeps a home for.
+The login you already have stays where the CLI put it (~/.claude, ~/.codex,
+~/.grok) and
+is the primary account; added accounts get a home of their own under
+~/.local/state/omarchy/agents/accounts/<provider>/<id>/ that holds only that
+account's credentials and links everything else back to the primary home, so
+conversation history, settings and skills stay one set across accounts.
+
+Each provider's registry is one JSON file beside those homes. It records which
+account is active — the one new sessions start as — how switching happens, and
+display-safe identity. Tokens never enter it and never leave this process.
+"""
+
+from __future__ import annotations
+
+import base64
+import datetime as dt
+import fcntl
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+PROVIDERS = {
+  "claude": {
+    "name": "Claude",
+    "home_env": "CLAUDE_CONFIG_DIR",
+    # Everything a session reads or writes that isn't tied to the login. A
+    # missing directory is created in the primary home first; a missing file
+    # is linked anyway, so whichever account writes it first writes it there.
+    "shared_dirs": ["projects", "skills", "agents", "commands", "plugins", "hooks", "themes", "output-styles", "file-history", "todos", "plans"],
+    "shared_files": ["settings.json", "CLAUDE.md", "history.jsonl", "keybindings.json"],
+    # Keys copied from the primary's ~/.claude.json into a new account's, so a
+    # second login keeps MCP servers, folder trust and onboarding choices.
+    "carried_keys": ["mcpServers", "projects", "theme", "hasCompletedOnboarding", "lastOnboardingVersion", "editorMode"],
+  },
+  "codex": {
+    "name": "Codex",
+    "home_env": "CODEX_HOME",
+    "shared_dirs": ["sessions", "archived_sessions", "prompts", "skills", "rules", "plugins"],
+    "shared_files": ["config.toml", "AGENTS.md", "history.jsonl", "hooks.json"],
+    "carried_keys": [],
+  },
+  "grok": {
+    "name": "Grok",
+    "home_env": "GROK_HOME",
+    "shared_dirs": ["sessions", "skills", "agents", "plugins", "installed-plugins", "marketplace-cache", "hooks", "memory", "memory-v2", "rules", "commands", "workflows", "personas", "worktrees"],
+    "shared_files": ["config.toml", "settings.json", "lsp.json", "pager.toml", "sandbox.toml", "trusted_folders.toml", "statusline.sh", "worktrees.db"],
+    "carried_keys": [],
+  },
+}
+
+DEFAULT_THRESHOLD = 95
+# Ids an account can't take because something else already answers to them:
+# `use next` cycles, a provider name is read as the provider when it comes
+# first, and the menu's Add Account row is `.add`.
+RESERVED_IDS = {"next", "add", "claude", "codex", "grok", "primary"}
+SWITCH_MODES = ("manual", "auto")
+
+
+class AccountError(Exception):
+  pass
+
+
+def text(english: str, *args: object) -> str:
+  """English with %1.. filled, in the session's language, from the shell's table."""
+  return subprocess.run(["omarchy-text", english, *map(str, args)], capture_output=True, text=True, check=True).stdout.rstrip("\n")
+
+
+# ------------------------------------------------------------------- paths
+
+
+def state_root() -> Path:
+  return Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state") / "omarchy" / "agents"
+
+
+def accounts_root() -> Path:
+  return state_root() / "accounts"
+
+
+def registry_path(provider: str) -> Path:
+  return accounts_root() / f"{provider}.json"
+
+
+def usage_record_path(provider: str) -> Path:
+  return state_root() / "usage" / f"{provider}.json"
+
+
+# The primary home is where the CLI keeps a login when nothing tells it
+# otherwise. It is deliberately not read from CLAUDE_CONFIG_DIR / CODEX_HOME /
+# GROK_HOME:
+# those are how an added account is selected, so honoring them here would make
+# whichever account launched this command look like the primary.
+def primary_home(provider: str) -> Path:
+  return Path.home() / f".{provider}"
+
+
+def account_home(provider: str, account: dict[str, Any]) -> Path:
+  home = str(account.get("home") or "")
+  return Path(home) if home else primary_home(provider)
+
+
+# Claude keeps its account file beside the config dir for the default home
+# (~/.claude.json) and inside it for any other.
+def claude_account_file(home: Path) -> Path:
+  if home == primary_home("claude"):
+    return Path.home() / ".claude.json"
+  return home / ".claude.json"
+
+
+# --------------------------------------------------------------- identity
+
+
+def read_json(path: Path) -> Any:
+  try:
+    return json.loads(path.read_text(encoding="utf-8"))
+  except Exception:
+    return None
+
+
+def plan_label(tier: str, subscription: str) -> str:
+  match = re.search(r"max_(\d+x)", tier or "", re.IGNORECASE)
+  if match:
+    return "Max " + match.group(1)
+  if subscription:
+    return subscription[0].upper() + subscription[1:]
+  return ""
+
+
+def jwt_claims(token: str) -> dict[str, Any]:
+  try:
+    payload = token.split(".")[1]
+    payload += "=" * (-len(payload) % 4)
+    claims = json.loads(base64.urlsafe_b64decode(payload.encode("ascii")))
+    return claims if isinstance(claims, dict) else {}
+  except Exception:
+    return {}
+
+
+# Who a home is signed in as, from files the CLI wrote at login. Only
+# display-safe fields come out; an empty accountId means nobody is signed in.
+def identity(provider: str, home: Path) -> dict[str, str]:
+  if provider == "claude":
+    account = (read_json(claude_account_file(home)) or {}).get("oauthAccount") or {}
+    login = (read_json(home / ".credentials.json") or {}).get("claudeAiOauth") or {}
+    return {
+      "accountId": str(account.get("accountUuid") or ""),
+      "email": str(account.get("emailAddress") or ""),
+      "org": str(account.get("organizationName") or ""),
+      "plan": plan_label(str(login.get("rateLimitTier") or ""), str(login.get("subscriptionType") or "")),
+    }
+
+  if provider == "grok":
+    return grok_identity(home)
+
+  auth = read_json(home / "auth.json") or {}
+  tokens = auth.get("tokens") or {}
+  claims = jwt_claims(str(tokens.get("id_token") or ""))
+  openai = claims.get("https://api.openai.com/auth") or {}
+  plan = str(openai.get("chatgpt_plan_type") or "")
+  return {
+    "accountId": str(tokens.get("account_id") or openai.get("chatgpt_account_id") or ""),
+    "email": str(claims.get("email") or ""),
+    "org": "",
+    "plan": plan[0].upper() + plan[1:] if plan else "",
+  }
+
+
+# Grok keeps one login per issuer in auth.json, and the plan only in the
+# settings it caches from xAI, as a JSON string inside that file.
+def grok_identity(home: Path) -> dict[str, str]:
+  auth = read_json(home / "auth.json") or {}
+  login = next((v for v in auth.values() if isinstance(v, dict)), {}) if isinstance(auth, dict) else {}
+  try:
+    settings = json.loads((read_json(home / "settings_cache.json") or {}).get("payload") or "{}").get("settings") or {}
+  except Exception:
+    settings = {}
+  return {
+    "accountId": str(login.get("user_id") or ""),
+    "email": str(login.get("email") or ""),
+    "org": "",
+    "plan": str(settings.get("subscription_tier_display") or ""),
+  }
+
+
+# ---------------------------------------------------------------- registry
+
+
+def slug(label: str) -> str:
+  return re.sub(r"[^a-z0-9]+", "-", label.lower()).strip("-")
+
+
+def empty_registry(provider: str) -> dict[str, Any]:
+  return {"active": "main", "switch": "manual", "threshold": DEFAULT_THRESHOLD, "alert": "", "accounts": []}
+
+
+def primary_entry(provider: str) -> dict[str, Any]:
+  entry = {"id": "main", "label": "Main", "home": "", "primary": True}
+  entry.update(identity(provider, primary_home(provider)))
+  return entry
+
+
+def normalized(provider: str, data: Any) -> dict[str, Any]:
+  registry = empty_registry(provider)
+  if isinstance(data, dict):
+    registry.update({key: data[key] for key in registry if key in data})
+  accounts = [a for a in registry["accounts"] if isinstance(a, dict) and a.get("id")]
+  if not any(a.get("primary") for a in accounts):
+    accounts.insert(0, primary_entry(provider))
+  registry["accounts"] = accounts
+  if registry["switch"] not in SWITCH_MODES:
+    registry["switch"] = "manual"
+  try:
+    registry["threshold"] = max(50, min(100, int(registry["threshold"])))
+  except Exception:
+    registry["threshold"] = DEFAULT_THRESHOLD
+  if not find(registry, registry["active"]):
+    registry["active"] = accounts[0]["id"]
+  return registry
+
+
+def load(provider: str) -> dict[str, Any]:
+  return normalized(provider, read_json(registry_path(provider)))
+
+
+def save(provider: str, registry: dict[str, Any]) -> None:
+  path = registry_path(provider)
+  path.parent.mkdir(parents=True, exist_ok=True)
+  os.chmod(path.parent, 0o700)
+  fd, tmp = tempfile.mkstemp(prefix=path.name + ".", dir=str(path.parent))
+  try:
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+      json.dump(registry, handle, indent=2)
+      handle.write("\n")
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, path)
+  except Exception:
+    Path(tmp).unlink(missing_ok=True)
+    raise
+
+
+# Every change is read-modify-write under one lock per provider, so the panel,
+# the autoswitch run after each usage update, and a command typed at a prompt
+# can't interleave and drop each other's edits.
+class Locked:
+  def __init__(self, provider: str):
+    self.provider = provider
+
+  def __enter__(self) -> dict[str, Any]:
+    accounts_root().mkdir(parents=True, exist_ok=True)
+    self.handle = open(accounts_root() / f".{self.provider}.lock", "w")
+    fcntl.flock(self.handle, fcntl.LOCK_EX)
+    self.registry = load(self.provider)
+    return self.registry
+
+  def __exit__(self, kind, value, traceback) -> None:
+    try:
+      if kind is None:
+        save(self.provider, self.registry)
+    finally:
+      fcntl.flock(self.handle, fcntl.LOCK_UN)
+      self.handle.close()
+
+
+def find(registry: dict[str, Any], account_id: str) -> dict[str, Any] | None:
+  for account in registry["accounts"]:
+    if account.get("id") == account_id:
+      return account
+  # `primary` names the login that was there first, whatever it's called now.
+  if account_id == "primary":
+    for account in registry["accounts"]:
+      if account.get("primary"):
+        return account
+  return None
+
+
+def active(registry: dict[str, Any]) -> dict[str, Any]:
+  return find(registry, registry["active"]) or registry["accounts"][0]
+
+
+# ------------------------------------------------------------------- homes
+
+
+# Lay the links that make an added account share everything but its login
+# with the primary home. Safe to repeat: an existing link or real file is left
+# as it is, so nothing an account wrote for itself is ever replaced.
+def link_shared(provider: str, home: Path) -> None:
+  spec = PROVIDERS[provider]
+  primary = primary_home(provider)
+  home.mkdir(parents=True, exist_ok=True)
+  os.chmod(home, 0o700)
+  for name in spec["shared_dirs"]:
+    (primary / name).mkdir(parents=True, exist_ok=True)
+  for name in spec["shared_dirs"] + spec["shared_files"]:
+    target = home / name
+    if target.exists() or target.is_symlink():
+      continue
+    target.symlink_to(primary / name)
+
+
+def carry_settings(provider: str, home: Path) -> None:
+  keys = PROVIDERS[provider]["carried_keys"]
+  if not keys:
+    return
+  source = read_json(claude_account_file(primary_home(provider))) or {}
+  path = claude_account_file(home)
+  data = read_json(path) or {}
+  for key in keys:
+    if key in source and key not in data:
+      data[key] = source[key]
+  fd, tmp = tempfile.mkstemp(prefix=path.name + ".", dir=str(path.parent))
+  with os.fdopen(fd, "w", encoding="utf-8") as handle:
+    json.dump(data, handle, indent=2)
+  os.chmod(tmp, 0o600)
+  os.replace(tmp, path)
+
+
+# A login in progress gets a scratch home beside the real ones, so an
+# abandoned or duplicate login never shows up as an account.
+def begin(provider: str) -> Path:
+  pending = accounts_root() / provider / ".pending"
+  pending.mkdir(parents=True, exist_ok=True)
+  os.chmod(pending.parent, 0o700)
+  home = Path(tempfile.mkdtemp(prefix="login-", dir=str(pending)))
+  link_shared(provider, home)
+  return home
+
+
+def register(provider: str, label: str, pending: Path) -> dict[str, Any]:
+  pending = pending.resolve()
+  if pending.parent != (accounts_root() / provider / ".pending").resolve():
+    raise AccountError(text("%1 is not a pending %2 login", pending, PROVIDERS[provider]['name']))
+
+  found = identity(provider, pending)
+  if not found["accountId"]:
+    shutil.rmtree(pending, ignore_errors=True)
+    raise AccountError(text("The login didn't finish, so no account was added."))
+
+  with Locked(provider) as registry:
+    # Each home is asked who it is now, not trusted from when it was added: a
+    # `claude auth login` run by hand in ~/.claude changes the primary.
+    for account in registry["accounts"]:
+      account.update(identity(provider, account_home(provider, account)))
+    for account in registry["accounts"]:
+      if account.get("accountId") == found["accountId"]:
+        shutil.rmtree(pending, ignore_errors=True)
+        raise AccountError(text(
+          "That's %1 (%2). Try again, and sign in as the other account in the private window.",
+          account["label"], found["email"] or text("already added"),
+        ))
+
+    label = label.strip() or found["email"].split("@")[0] or "Account"
+    account_id = unique_id(provider, registry, label)
+
+    # Everything that can fail happens while the login is still pending, where
+    # the add command cleans it up, or is undone: a home that isn't in the
+    # registry would keep a sign-in nothing can manage.
+    carry_settings(provider, pending)
+    home = accounts_root() / provider / account_id
+    pending.rename(home)
+    entry = {"id": account_id, "label": label, "home": str(home), "primary": False}
+    entry.update(found)
+    registry["accounts"].append(entry)
+    try:
+      save(provider, registry)
+    except Exception:
+      registry["accounts"].pop()
+      home.rename(pending)
+      raise
+    return entry
+
+
+# The id an account answers to, from its label. It can't clash with another
+# account, a routing keyword, or a home left under that name by an account
+# that has since been renamed.
+def unique_id(provider: str, registry: dict[str, Any], label: str, keep: dict[str, Any] | None = None) -> str:
+  base = slug(label) or "account"
+  account_id, n = base, 2
+  while True:
+    taken = find(registry, account_id)
+    if account_id not in RESERVED_IDS and (taken is None or taken is keep):
+      if keep is not None or not (accounts_root() / provider / account_id).exists():
+        return account_id
+    account_id, n = f"{base}-{n}", n + 1
+
+
+# A new label, and the id that follows from it. The home stays where it is:
+# sessions already running in it hold that path.
+def rename(provider: str, target: str, label: str) -> dict[str, Any]:
+  label = label.strip()
+  if not label:
+    raise AccountError(text("Give the account a name"))
+  with Locked(provider) as registry:
+    account = find(registry, target)
+    if not account:
+      raise AccountError(text("No %1 account named %2", PROVIDERS[provider]['name'], target))
+    new_id = unique_id(provider, registry, label, keep=account)
+    if not account.get("primary") and not account.get("home"):
+      account["home"] = str(account_home(provider, account))
+    if registry["active"] == account["id"]:
+      registry["active"] = new_id
+    registry["alert"] = ""
+    account["id"] = new_id
+    account["label"] = label
+    return dict(account)
+
+
+# Save who each home is signed in as now. A login run in a home, through the
+# panel or the CLI, changes it, and the usage records take their names and
+# emails from here.
+def refresh(provider: str) -> None:
+  with Locked(provider) as registry:
+    for account in registry["accounts"]:
+      account.update(identity(provider, account_home(provider, account)))
+
+
+def use(provider: str, target: str) -> tuple[dict[str, Any], dict[str, Any]]:
+  with Locked(provider) as registry:
+    previous = active(registry)
+    if target == "next":
+      ids = [a["id"] for a in registry["accounts"]]
+      target = ids[(ids.index(previous["id"]) + 1) % len(ids)]
+    account = find(registry, target)
+    if not account:
+      raise AccountError(text("No %1 account named %2", PROVIDERS[provider]['name'], target))
+    registry["active"] = account["id"]
+    registry["alert"] = ""
+    if not account.get("primary"):
+      link_shared(provider, account_home(provider, account))
+    return previous, account
+
+
+# Whether a running session was started in this home. Removing it would pull
+# the login out from under that session, which must never be touched.
+def home_in_use(provider: str, home: Path) -> bool:
+  wanted = f"{PROVIDERS[provider]['home_env']}=".encode()
+  resolved = home.resolve()
+  for environ in Path("/proc").glob("[0-9]*/environ"):
+    try:
+      entries = environ.read_bytes().split(b"\0")
+    except OSError:
+      continue
+    for entry in entries:
+      if entry.startswith(wanted) and Path(entry[len(wanted):].decode(errors="replace")).resolve() == resolved:
+        return True
+  return False
+
+
+def remove(provider: str, target: str) -> dict[str, Any]:
+  with Locked(provider) as registry:
+    account = find(registry, target)
+    if not account:
+      raise AccountError(text("No %1 account named %2", PROVIDERS[provider]['name'], target))
+    if account.get("primary"):
+      raise AccountError(text("%1 is the login in %2; it can't be removed here.", account["label"], primary_home(provider)))
+    home = account_home(provider, account)
+    if home_in_use(provider, home):
+      raise AccountError(text("A running %1 session uses %2. Quit it first, then remove the account.", PROVIDERS[provider]['name'], account["label"]))
+    # Only the account's own directory goes. Its links point into the primary
+    # home, and rmtree removes a link without following it.
+    if home.resolve().parent == (accounts_root() / provider).resolve():
+      shutil.rmtree(home, ignore_errors=True)
+    registry["accounts"] = [a for a in registry["accounts"] if a["id"] != account["id"]]
+    if registry["active"] == account["id"]:
+      registry["active"] = registry["accounts"][0]["id"]
+    return account
+
+
+def set_mode(provider: str, mode: str, threshold: str | None) -> dict[str, Any]:
+  if mode not in SWITCH_MODES:
+    raise AccountError(text("Switch mode is manual or auto"))
+  with Locked(provider) as registry:
+    registry["switch"] = mode
+    if threshold is not None:
+      try:
+        registry["threshold"] = max(50, min(100, int(threshold)))
+      except ValueError:
+        raise AccountError(text("The threshold is a percentage between 50 and 100"))
+    registry["alert"] = ""
+    return dict(registry)
+
+
+# ------------------------------------------------------------- autoswitch
+
+
+def window_open(limit: dict[str, Any], now: dt.datetime) -> bool:
+  raw = str(limit.get("resetsAt") or "")
+  if not raw:
+    return True
+  try:
+    resets_at = dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
+  except Exception:
+    return True
+  if resets_at.tzinfo is None:
+    resets_at = resets_at.replace(tzinfo=dt.timezone.utc)
+  return resets_at > now
+
+
+# How spent an account is: its fullest window that hasn't reset yet, in
+# percent. A window whose reset has passed counts as empty even when the
+# numbers are stale, since that's exactly what a reset means. None when
+# nothing is known at all.
+def peak(limits: Any, now: dt.datetime) -> float | None:
+  if not isinstance(limits, list):
+    return None
+  known = [l for l in limits if isinstance(l, dict) and isinstance(l.get("percent"), (int, float))]
+  if not known:
+    return None
+  open_windows = [float(l["percent"]) * 100 for l in known if window_open(l, now)]
+  return max(open_windows) if open_windows else 0.0
+
+
+def next_reset(limits: Any, now: dt.datetime) -> dt.datetime | None:
+  times = []
+  for limit in limits if isinstance(limits, list) else []:
+    try:
+      when = dt.datetime.fromisoformat(str(limit.get("resetsAt") or "").replace("Z", "+00:00"))
+    except Exception:
+      continue
+    if when.tzinfo is None:
+      when = when.replace(tzinfo=dt.timezone.utc)
+    if when > now:
+      times.append(when)
+  return min(times) if times else None
+
+
+# When an account over the threshold drops back under it: once every window
+# holding it there has reset, which is the latest of those resets. A 10%
+# session resetting in an hour doesn't help an account whose weekly window is
+# full for six more days. None when a blocking window never says.
+def available_at(limits: Any, threshold: float, now: dt.datetime) -> dt.datetime | None:
+  latest = None
+  for limit in limits if isinstance(limits, list) else []:
+    if not isinstance(limit, dict) or not isinstance(limit.get("percent"), (int, float)):
+      continue
+    if float(limit["percent"]) * 100 < threshold or not window_open(limit, now):
+      continue
+    try:
+      when = dt.datetime.fromisoformat(str(limit.get("resetsAt") or "").replace("Z", "+00:00"))
+    except Exception:
+      return None
+    if when.tzinfo is None:
+      when = when.replace(tzinfo=dt.timezone.utc)
+    latest = when if latest is None or when > latest else latest
+  return latest
+
+
+def duration(delta: dt.timedelta) -> str:
+  minutes = max(1, int(delta.total_seconds() // 60))
+  hours, minutes = divmod(minutes, 60)
+  days, hours = divmod(hours, 24)
+  if days:
+    return text("%1d %2h", days, hours)
+  if hours:
+    return text("%1h %2m", hours, minutes)
+  return text("%1m", minutes)
+
+
+# The whole switching policy, with no I/O: given the registry and the per
+# account limits from the usage record, what should happen. Returns None when
+# nothing should, or {"action": "switch"|"notify"|"exhausted", ...}.
+#
+# Only the active account crossing the threshold starts anything, so auto
+# mode never flaps back to an account that just reset. `alert` remembers the
+# last thing said, so a shell restart or the next refresh doesn't repeat it.
+#
+# Numbers kept from an earlier check may be out of date, but a parked account's
+# sign-in lapses within hours and can't be checked again until a session runs
+# in it. So a stale account is still a candidate: among accounts with room, one
+# checked just now wins, but room comes first. An account within 15 points of
+# the threshold (where the panel starts checking more often) is near its limit
+# however fresh its numbers are.
+def decide(registry: dict[str, Any], usage: dict[str, Any], now: dt.datetime, stale: frozenset[str] = frozenset()) -> dict[str, Any] | None:
+  threshold = float(registry["threshold"])
+  current = active(registry)
+  current_peak = peak(usage.get(current["id"]), now)
+  if current_peak is None or current_peak < threshold:
+    return {"action": "clear"} if registry.get("alert") else None
+
+  candidates = []
+  for account in registry["accounts"]:
+    if account["id"] == current["id"]:
+      continue
+    level = peak(usage.get(account["id"]), now)
+    if level is None or level >= threshold:
+      continue
+    reset = next_reset(usage.get(account["id"]), now) or dt.datetime.max.replace(tzinfo=dt.timezone.utc)
+    candidates.append((level >= threshold - 15, account["id"] in stale, level, reset, account))
+  candidates.sort(key=lambda c: c[:4])
+
+  if candidates:
+    _, _, level, _, target = candidates[0]
+    action = "switch" if registry["switch"] == "auto" else "notify"
+    alert = f"{action}:{current['id']}:{target['id']}"
+    if registry.get("alert") == alert:
+      return None
+    return {"action": action, "alert": alert, "from": current, "to": target, "fromPeak": current_peak, "toPeak": level}
+
+  alert = f"exhausted:{current['id']}"
+  if registry.get("alert") == alert or len(registry["accounts"]) < 2:
+    return None
+  # Only when every account is known to be over. One that's signed out or
+  # couldn't be checked might have room, so there's nothing honest to say.
+  if any(peak(usage.get(a["id"]), now) is None for a in registry["accounts"]):
+    return None
+  soonest = None
+  for account in registry["accounts"]:
+    reset = available_at(usage.get(account["id"]), threshold, now)
+    if reset and (soonest is None or reset < soonest[0]):
+      soonest = (reset, account)
+  return {"action": "exhausted", "alert": alert, "from": current, "fromPeak": current_peak, "soonest": soonest}
+
+
+# Limits per account id. An account nobody is signed in to is left out, so it
+# is never a candidate: its cached headroom is no use to a session that can't
+# start. One whose token merely expired stays in, since a session refreshes it.
+def usage_by_account(provider: str) -> tuple[dict[str, Any], frozenset[str]]:
+  record = read_json(usage_record_path(provider)) or {}
+  accounts = [
+    a for a in record.get("accounts") or []
+    if isinstance(a, dict) and a.get("id") and a.get("usageStatusText") != "Waiting for auth"
+  ]
+  return (
+    {str(a["id"]): a.get("limits") for a in accounts},
+    frozenset(str(a["id"]) for a in accounts if a.get("stale") is True),
+  )
+
+
+def notify(title: str, body: str, action: list[str] | None = None) -> None:
+  command = ["omarchy-notification-send", "--app-name", "Omarchy Agents", "-g", "󰚩", title, body]
+  if action:
+    command += ["--exec"] + action
+  subprocess.run(command, check=False)
+
+
+# Returns True when the active account changed.
+def autoswitch(provider: str, now: dt.datetime | None = None) -> bool:
+  now = now or dt.datetime.now(dt.timezone.utc)
+  name = PROVIDERS[provider]["name"]
+  with Locked(provider) as registry:
+    if len(registry["accounts"]) < 2:
+      return False
+    usage, stale = usage_by_account(provider)
+    decision = decide(registry, usage, now, stale)
+    if decision is None:
+      return False
+    if decision["action"] == "clear":
+      registry["alert"] = ""
+      return False
+
+    registry["alert"] = decision["alert"]
+    source = decision["from"]
+    threshold = registry["threshold"]
+    if decision["action"] == "exhausted":
+      soonest = decision["soonest"]
+      staying = text("Staying on %1.", source["label"])
+      if soonest:
+        staying = text("Staying on %1. %2 resets in %3.", source["label"], soonest[1]["label"], duration(soonest[0] - now))
+      notify(text("All %1 accounts are over %2%", name, threshold), staying)
+      return False
+
+    target = decision["to"]
+    headline = text("%1 is at %2% of a %3 limit", source["label"], round(decision["fromPeak"]), name)
+    if decision["action"] == "switch":
+      registry["active"] = target["id"]
+      if not target.get("primary"):
+        link_shared(provider, account_home(provider, target))
+      notify(headline, text("New %1 sessions now use %2 (%3%). Running sessions stay on %4.", name, target["label"], round(decision["toPeak"]), source["label"]))
+      return True
+    notify(
+      headline,
+      text("%1 is at %2%. Click to switch new sessions to it.", target["label"], round(decision["toPeak"])),
+      ["omarchy-agent-account-use", provider, target["id"]],
+    )
+    return False
+
+
+# --------------------------------------------------------------------- CLI
+
+
+def provider_arg(args: list[str]) -> str:
+  if not args or args[0] not in PROVIDERS:
+    raise AccountError("Name a provider: claude, codex, or grok")
+  return args[0]
+
+
+def summary(provider: str, registry: dict[str, Any]) -> dict[str, Any]:
+  # Identity is re-read from each home rather than trusted from the registry:
+  # a `claude auth login` run by hand in a home changes who it is.
+  for account in registry["accounts"]:
+    account.update(identity(provider, account_home(provider, account)))
+  return {
+    "provider": provider,
+    "name": PROVIDERS[provider]["name"],
+    "active": registry["active"],
+    "switch": registry["switch"],
+    "threshold": registry["threshold"],
+    "accounts": [
+      {key: account.get(key, "") for key in ("id", "label", "email", "org", "plan", "primary")}
+      | {
+        "home": str(account_home(provider, account)),
+        "active": account["id"] == registry["active"],
+        "signedIn": bool(account.get("accountId")),
+      }
+      for account in registry["accounts"]
+    ],
+  }
+
+
+def main(argv: list[str]) -> int:
+  if not argv:
+    print(__doc__.strip().splitlines()[0], file=sys.stderr)
+    return 1
+  command, args = argv[0], argv[1:]
+  try:
+    if command == "registry":
+      provider = provider_arg(args)
+      print(json.dumps(summary(provider, load(provider))))
+    elif command == "list":
+      providers = [provider_arg(args)] if args else list(PROVIDERS)
+      print(json.dumps([summary(p, load(p)) for p in providers]))
+    elif command == "home":
+      # Empty for the primary, so launching it needs no environment at all.
+      provider = provider_arg(args)
+      registry = read_json(registry_path(provider))
+      if registry:
+        account = active(normalized(provider, registry))
+        if not account.get("primary"):
+          print(account_home(provider, account))
+    elif command == "homes":
+      provider = provider_arg(args)
+      registry = load(provider)
+      for account in registry["accounts"]:
+        print("\t".join([account["id"], str(account_home(provider, account)), "1" if account["id"] == registry["active"] else "0"]))
+    elif command == "refresh":
+      for provider in ([provider_arg(args)] if args else list(PROVIDERS)):
+        if registry_path(provider).exists():
+          refresh(provider)
+    elif command == "begin":
+      print(begin(provider_arg(args)))
+    elif command == "register":
+      provider = provider_arg(args)
+      if len(args) < 3:
+        raise AccountError("register <provider> <label> <pending-home>")
+      print(json.dumps(register(provider, args[1], Path(args[2]))))
+    elif command == "use":
+      provider = provider_arg(args)
+      previous, account = use(provider, args[1] if len(args) > 1 else "next")
+      print(json.dumps({"previous": previous, "active": account}))
+    elif command == "remove":
+      provider = provider_arg(args)
+      if len(args) < 2:
+        raise AccountError("remove <provider> <account>")
+      print(json.dumps(remove(provider, args[1])))
+    elif command == "rename":
+      provider = provider_arg(args)
+      if len(args) < 3:
+        raise AccountError("rename <provider> <account> <label>")
+      print(json.dumps(rename(provider, args[1], " ".join(args[2:]))))
+    elif command == "mode":
+      provider = provider_arg(args)
+      if len(args) < 2:
+        raise AccountError("mode <provider> <manual|auto> [threshold]")
+      set_mode(provider, args[1], args[2] if len(args) > 2 else None)
+    elif command == "link":
+      provider = provider_arg(args)
+      link_shared(provider, Path(args[1]))
+    elif command == "autoswitch":
+      # Prints each provider whose active account changed, so the caller
+      # knows which usage records to collect again.
+      for provider in ([provider_arg(args)] if args else list(PROVIDERS)):
+        if registry_path(provider).exists() and autoswitch(provider):
+          print(provider)
+    else:
+      raise AccountError(f"Unknown command: {command}")
+  except AccountError as error:
+    print(error, file=sys.stderr)
+    return 1
+  return 0
+
+
+if __name__ == "__main__":
+  raise SystemExit(main(sys.argv[1:]))

bin/omarchy-agent-account-use

@@ -0,0 +1,39 @@
+#!/bin/bash
+
+# omarchy:summary=Choose which Claude, Codex, or Grok account new sessions use
+# omarchy:args=[claude|codex|grok] [account|next]
+# omarchy:examples=omarchy agent account use work | omarchy agent account use main | omarchy agent account use codex next
+
+set -uo pipefail
+
+# The provider can be left out when it's your default agent:
+# `omarchy agent account use work`.
+if [[ ${1:-} != "claude" && ${1:-} != "codex" && ${1:-} != "grok" ]]; then
+  default=$(omarchy-default-agent)
+  [[ $default == "claude" || $default == "codex" || $default == "grok" ]] && set -- "$default" "$@"
+fi
+
+case "${1:-}" in
+claude) name="Claude" ;;
+codex) name="Codex" ;;
+grok) name="Grok" ;;
+*)
+  echo "Usage: omarchy-agent-account-use [claude|codex|grok] [account|next]" >&2
+  exit 1
+  ;;
+esac
+
+result=$(omarchy-agent-account-state use "$1" "${2:-next}") || exit 1
+
+previous=$(jq -r .previous.label <<<"$result")
+active=$(jq -r '.active.label + (if (.active.plan // "") != "" then " (" + .active.plan + ")" else "" end)' <<<"$result")
+
+if [[ $(jq -r .previous.id <<<"$result") == "$(jq -r .active.id <<<"$result")" ]]; then
+  echo "New $name sessions already use $active."
+else
+  message=$(omarchy-text "Running sessions stay on %1." "$previous")
+  echo "New $name sessions now use $active. $message"
+  omarchy-notification-send -g 󰚩 "$(omarchy-text "New %1 sessions now use %2" "$name" "$active")" "$message"
+  # The usage record's own limits describe the active account.
+  omarchy-agent-usage-update --limits-only "$1" >/dev/null 2>&1 &
+fi

bin/omarchy-agent-crash

@@ -0,0 +1,52 @@
+#!/bin/bash
+
+# omarchy:summary=Diagnose a crashed process with the default coding agent
+# omarchy:args=<pid> [comm] [exe] [signal]
+# omarchy:examples=omarchy agent crash 1516893
+
+# Clicked from a "Process crashed:" notification, or run by hand against any PID
+# in `coredumpctl list`. The method lives in the diagnose-crash skill so it is
+# edited in one place and works with whichever agent is default; this only
+# gathers the facts and points at it.
+
+set -euo pipefail
+
+pid=${1:?usage: omarchy-agent-crash <pid> [comm] [exe] [signal]}
+
+if [[ ! $pid =~ ^[0-9]+$ ]]; then
+  echo "Not a PID: $pid" >&2
+  echo "Usage: omarchy agent crash <pid>   (see: coredumpctl list)" >&2
+  exit 1
+fi
+
+comm=${2:-unknown}
+exe=${3:-unknown}
+signal=${4:-unknown}
+
+skill="$OMARCHY_PATH/default/agents/skills/diagnose-crash/SKILL.md"
+
+# Looked up live so a hand-run PID still gets a timestamp. A rotated-away core
+# only costs the timestamp, so failure is tolerated.
+when=$(coredumpctl list "$pid" --no-pager --no-legend 2>/dev/null | tail -1 | cut -d' ' -f1-4) || true
+when=${when:-unknown}
+
+prompt=$(
+  cat <<PROMPT
+A process crashed on this Omarchy machine and I want to know why.
+
+What systemd-coredump recorded:
+  process:  $comm
+  PID:      $pid
+  binary:   $exe
+  signal:   $signal
+  time:     $when
+
+Use the diagnose-crash skill: it covers how to investigate, what to report, and
+when a crash is worth reporting upstream to Omarchy. If your harness has no skill
+mechanism, read the skill files directly and follow them instead:
+
+  $skill
+PROMPT
+)
+
+exec omarchy-agent --prompt "$prompt"

bin/omarchy-agent-prompt

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# omarchy:summary=Launch the default coding agent with a prompt
+# omarchy:args=[--inline] <prompt...>
+# omarchy:examples=omarchy agent prompt "Review this project"
+
+# Prompts live here rather than on `omarchy agent`, where a bare prompt would
+# shadow the subcommands under that group.
+
+set -euo pipefail
+
+inline=()
+if [[ ${1:-} == "--inline" ]]; then
+  inline=(--inline)
+  shift
+fi
+
+if (($# == 0)); then
+  echo "Usage: omarchy agent prompt [--inline] <prompt...>" >&2
+  exit 1
+fi
+
+exec omarchy-agent "${inline[@]}" --prompt "$*"

bin/omarchy-agent-usage-fireworks

@@ -0,0 +1,558 @@
+#!/usr/bin/python3
+# omarchy:summary=Print the Fireworks usage record as JSON
+# omarchy:args=[--force] [--limits-only]
+# omarchy:hidden=true
+"""Collect Fireworks serverless usage into one display-ready JSON record.
+
+Token stats come from the Fireworks billing API grouped by day and model for
+the last 30 days. Fireworks does not expose its prepaid ledger, so the record
+carries an estimated balance instead of rate limits: the credits configured in
+~/.config/omarchy/agents/fireworks.json minus rated account costs since the
+funding date. The agents panel only ever reads the JSON this prints.
+"""
+
+from __future__ import annotations
+
+import argparse
+import configparser
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import date, datetime, time, timedelta, timezone
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+from typing import Any
+
+AGENT_ID = "fireworks"
+AGENT_NAME = "Fireworks"
+AUTH_HELP = "Set FIREWORKS_API_KEY, run `firectl set-api-key`, or sign in to Fireworks in pi or opencode."
+API_BASE_URL = "https://api.fireworks.ai"
+
+
+class FireworksError(Exception):
+  pass
+
+
+def number(value: Any) -> int:
+  try:
+    return max(0, round(float(value or 0)))
+  except (TypeError, ValueError):
+    return 0
+
+
+def money_value(value: Any) -> Decimal:
+  if not isinstance(value, dict):
+    return Decimal("0")
+  try:
+    units = Decimal(str(value.get("units", 0) or 0))
+    nanos = Decimal(str(value.get("nanos", 0) or 0)) / Decimal("1000000000")
+    return units + nanos
+  except (InvalidOperation, TypeError, ValueError):
+    return Decimal("0")
+
+
+def model_id(row: dict[str, Any]) -> str:
+  group = row.get("group") if isinstance(row.get("group"), dict) else {}
+  raw = group.get("model_name") or row.get("modelName") or "unknown"
+  name = str(raw).rstrip("/").split("/")[-1] or "unknown"
+  return re.sub(r"(?<=\d)p(?=\d)", ".", name)
+
+
+def row_date(row: dict[str, Any]) -> str:
+  # The query asks for day buckets in the local timezone, but the API reports
+  # each bucket's boundary in UTC: local Aug 7 starts at Aug 6 22:00Z east of
+  # Greenwich. Convert back to local time to recover the day the bucket names —
+  # taking the raw date prefix would file every day under its predecessor.
+  raw = str(row.get("startTime") or "")
+  if not raw:
+    return ""
+  try:
+    parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+  except ValueError:
+    return raw[:10] if len(raw) >= 10 else ""
+  if parsed.tzinfo is None:
+    parsed = parsed.replace(tzinfo=timezone.utc)
+  return parsed.astimezone().date().isoformat()
+
+
+def empty_bucket() -> dict[str, int]:
+  return {
+    "inputTokens": 0,
+    "outputTokens": 0,
+    "cacheReadInputTokens": 0,
+    "cacheCreationInputTokens": 0,
+  }
+
+
+def empty_stats() -> dict[str, Any]:
+  return {
+    "todayPrompts": 0,
+    "todaySessions": 0,
+    "todayTotalTokens": 0,
+    "todayTokensByModel": {},
+    "recentDays": [],
+    "totalPrompts": 0,
+    "totalSessions": 0,
+    "activeDays": 0,
+    "activeDates": [],
+    "modelUsage": {},
+  }
+
+
+def base_record(**overrides: Any) -> dict[str, Any]:
+  record: dict[str, Any] = {
+    "schemaVersion": 1,
+    "id": AGENT_ID,
+    "name": AGENT_NAME,
+    "updatedAt": datetime.now(timezone.utc).isoformat(),
+    "ready": False,
+    "hasLocalStats": False,
+    # Billing-API numbers are account-global, not machine-local: every synced
+    # device reports the same truth, so aggregation must not sum them.
+    "scope": "account",
+    # The billing API reports tokens, never prompt or session counts; the
+    # panel keeps those numbers out of today's tooltip when this is false.
+    "hasPromptStats": False,
+    "tierLabel": "Prepaid",
+    "usageStatusText": "",
+    "authHelpText": "",
+    "limits": [],
+  }
+  record.update(empty_stats())
+  record.update(overrides)
+  return record
+
+
+def summarize_usage(payload: dict[str, Any], today: date | None = None) -> dict[str, Any]:
+  today = today or datetime.now().astimezone().date()
+  recent_dates = [(today - timedelta(days=offset)).isoformat() for offset in range(6, -1, -1)]
+  recent = {day: 0 for day in recent_dates}
+  today_by_model: dict[str, int] = {}
+  model_usage: dict[str, dict[str, int]] = {}
+  active_dates: set[str] = set()
+
+  rows = payload.get("serverlessCosts")
+  if not isinstance(rows, list):
+    rows = []
+
+  for raw_row in rows:
+    if not isinstance(raw_row, dict):
+      continue
+    day = row_date(raw_row)
+    model = model_id(raw_row)
+    prompt = number(raw_row.get("promptTokens"))
+    cached = min(prompt, number(raw_row.get("cachedPromptTokens")))
+    uncached = number(raw_row.get("uncachedPromptTokens"))
+    if "uncachedPromptTokens" not in raw_row:
+      uncached = max(0, prompt - cached)
+    output = number(raw_row.get("completionTokens"))
+    total = uncached + cached + output
+    if total <= 0:
+      continue
+
+    bucket = model_usage.setdefault(model, empty_bucket())
+    bucket["inputTokens"] += uncached
+    bucket["outputTokens"] += output
+    bucket["cacheReadInputTokens"] += cached
+
+    if day:
+      active_dates.add(day)
+    if day in recent:
+      recent[day] += total
+    if day == today.isoformat():
+      today_by_model[model] = today_by_model.get(model, 0) + total
+
+  return {
+    "todayTotalTokens": sum(today_by_model.values()),
+    "todayTokensByModel": today_by_model,
+    "recentDays": [{"date": day, "messageCount": recent[day]} for day in recent_dates],
+    "activeDays": len(active_dates),
+    "activeDates": sorted(active_dates),
+    "modelUsage": model_usage,
+  }
+
+
+def read_auth_file(path: Path) -> tuple[str, str]:
+  if not path.is_file():
+    return "", ""
+
+  parser = configparser.ConfigParser(interpolation=None)
+  try:
+    parser.read(path)
+  except configparser.Error:
+    return "", ""
+
+  api_key = ""
+  account_id = ""
+  sections = [parser.defaults()]
+  sections.extend(parser[section] for section in parser.sections())
+  for values in sections:
+    api_key = api_key or str(values.get("api_key", values.get("api-key", ""))).strip()
+    account_id = account_id or str(values.get("account_id", values.get("account-id", ""))).strip()
+  return api_key, account_id
+
+
+def pi_auth_path() -> Path:
+  agent_dir = Path(os.environ.get("PI_CODING_AGENT_DIR") or (Path.home() / ".pi" / "agent"))
+  return agent_dir / "auth.json"
+
+
+def opencode_auth_path() -> Path:
+  data_home = Path(os.environ.get("XDG_DATA_HOME") or (Path.home() / ".local" / "share"))
+  return data_home / "opencode" / "auth.json"
+
+
+PI_ENV_REFERENCE = re.compile(r"\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))")
+
+
+def resolve_pi_key(raw: Any) -> str:
+  # pi credential keys are literals, $ENV_VAR/${ENV_VAR} references, or
+  # !command shell lookups. The collector resolves the first two; command
+  # lookups stay pi-only and are skipped rather than sent to the API verbatim.
+  key = str(raw or "").strip()
+  if not key or key.startswith("!"):
+    return ""
+  # Escapes survive interpolation as sentinels, then restore.
+  key = key.replace("$$", "\x00").replace("$!", "\x01")
+
+  unresolved = False
+
+  def substitute(match: re.Match[str]) -> str:
+    nonlocal unresolved
+    value = os.environ.get(match.group(1) or match.group(2), "")
+    if not value:
+      unresolved = True
+    return value
+
+  key = PI_ENV_REFERENCE.sub(substitute, key)
+  if unresolved:
+    return ""
+  return key.replace("\x00", "$").replace("\x01", "!")
+
+
+def read_pi_key(path: Path) -> str:
+  try:
+    parsed = json.loads(path.read_text())
+  except (OSError, json.JSONDecodeError):
+    return ""
+  entry = parsed.get("fireworks") if isinstance(parsed, dict) else None
+  if not isinstance(entry, dict):
+    return ""
+  if entry.get("type") not in (None, "api_key"):
+    return ""
+  return resolve_pi_key(entry.get("key"))
+
+
+def read_opencode_key(path: Path) -> str:
+  try:
+    parsed = json.loads(path.read_text())
+  except (OSError, json.JSONDecodeError):
+    return ""
+  entry = parsed.get("fireworks-ai") if isinstance(parsed, dict) else None
+  if not isinstance(entry, dict):
+    return ""
+  return str(entry.get("key") or "").strip()
+
+
+def config_path() -> Path:
+  config_home = Path(os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config"))
+  return config_home / "omarchy" / "agents" / "fireworks.json"
+
+
+def read_config() -> dict[str, Any]:
+  try:
+    parsed = json.loads(config_path().read_text())
+    return parsed if isinstance(parsed, dict) else {}
+  except (OSError, json.JSONDecodeError):
+    return {}
+
+
+def credentials(auth_path: Path, config: dict[str, Any]) -> tuple[str, str]:
+  file_key, file_account = read_auth_file(auth_path)
+  # Agent logins are the fallback ladder below an explicit key or a firectl
+  # login: pi first as Omarchy's default agent, opencode as the last resort.
+  api_key = (
+    str(os.environ.get("FIREWORKS_API_KEY", "")).strip()
+    or file_key
+    or read_pi_key(pi_auth_path())
+    or read_opencode_key(opencode_auth_path())
+  )
+  account_id = (
+    str(os.environ.get("FIREWORKS_ACCOUNT_ID", "")).strip()
+    or str(config.get("accountId") or "").strip()
+    or file_account
+  )
+  return api_key, account_id
+
+
+def normalize_account_id(value: str) -> str:
+  return str(value or "").strip().removeprefix("accounts/").strip("/")
+
+
+def timezone_name() -> str:
+  configured = str(os.environ.get("TZ", "")).strip()
+  if configured:
+    return configured
+  try:
+    target = (Path("/etc/localtime").resolve()).as_posix()
+    marker = "/zoneinfo/"
+    if marker in target:
+      return target.split(marker, 1)[1]
+  except OSError:
+    pass
+  return "UTC"
+
+
+def local_midnight_utc(day: date) -> str:
+  # The API buckets by the requested timezone, so the window must run between
+  # local midnights — expressed in UTC, since a bare date with a Z suffix
+  # shifts the window by the UTC offset and clips today's tail west of
+  # Greenwich.
+  return datetime.combine(day, time.min).astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def iso_timestamp(value: str) -> str:
+  raw = str(value or "").strip()
+  if not raw:
+    return ""
+  try:
+    if len(raw) == 10:
+      parsed = datetime.combine(date.fromisoformat(raw), time.min, tzinfo=timezone.utc)
+    else:
+      parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+      if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+  except ValueError:
+    raise FireworksError("Fireworks fundedAt must be an ISO date such as 2026-07-01")
+
+
+class FireworksClient:
+  def __init__(self, api_key: str, base_url: str = API_BASE_URL):
+    self.api_key = api_key
+    self.base_url = base_url.rstrip("/")
+
+  def request(
+    self,
+    path: str,
+    query: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
+  ) -> dict[str, Any]:
+    url = self.base_url + path
+    if query:
+      url += "?" + urllib.parse.urlencode(query, doseq=True)
+    data = None if body is None else json.dumps(body).encode("utf-8")
+    request = urllib.request.Request(
+      url,
+      data=data,
+      method="POST" if body is not None else "GET",
+      headers={
+        "Authorization": "Bearer " + self.api_key,
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+      },
+    )
+    try:
+      with urllib.request.urlopen(request, timeout=15) as response:
+        decoded = json.load(response)
+        return decoded if isinstance(decoded, dict) else {}
+    except urllib.error.HTTPError as error:
+      if error.code == 401:
+        raise FireworksError("Fireworks rejected the API key")
+      if error.code == 403:
+        raise FireworksError("The Fireworks API key cannot read billing data")
+      if error.code == 404:
+        raise FireworksError("Fireworks account not found")
+      raise FireworksError(f"Fireworks API returned HTTP {error.code}")
+    except urllib.error.URLError as error:
+      raise FireworksError("Could not reach the Fireworks API") from error
+    except (json.JSONDecodeError, TimeoutError) as error:
+      raise FireworksError("Fireworks returned an invalid billing response") from error
+
+  def discover_account(self) -> tuple[str, dict[str, Any]]:
+    payload = self.request("/v1/accounts", query={"pageSize": 100})
+    accounts = [item for item in payload.get("accounts", []) if isinstance(item, dict)]
+    if len(accounts) == 1:
+      account = accounts[0]
+      return normalize_account_id(str(account.get("name") or "")), account
+    if not accounts:
+      raise FireworksError("No Fireworks account is available for this API key")
+    raise FireworksError("Set accountId in fireworks.json when the API key can access multiple accounts")
+
+  def account(self, account_id: str) -> dict[str, Any]:
+    quoted = urllib.parse.quote(normalize_account_id(account_id), safe="")
+    return self.request(f"/v1/accounts/{quoted}")
+
+  def usage(self, account_id: str, start_day: date, end_day: date) -> dict[str, Any]:
+    quoted = urllib.parse.quote(normalize_account_id(account_id), safe="")
+    query = {
+      "startTime": local_midnight_utc(start_day),
+      "endTime": local_midnight_utc(end_day),
+      "usageType": "SERVERLESS",
+      "timezone": timezone_name(),
+      "groupBy": ["model_name"],
+    }
+    # 30 days grouped by model can exceed one page; follow the continuation
+    # tokens or heavy accounts lose their tail. The bound is a runaway stop.
+    rows: list[Any] = []
+    for _ in range(20):
+      payload = self.request(f"/v1/accounts/{quoted}/billingUsage", query=query)
+      page = payload.get("serverlessCosts")
+      if isinstance(page, list):
+        rows.extend(page)
+      token = str(payload.get("nextPageToken") or "")
+      if not token:
+        break
+      query = dict(query, pageToken=token)
+    return {"serverlessCosts": rows}
+
+  def spent(self, account_id: str, start_at: str, end_at: str) -> Decimal:
+    quoted = urllib.parse.quote(normalize_account_id(account_id), safe="")
+    body = {
+      "startTime": start_at,
+      "endTime": end_at,
+      "scope": "ACCOUNT",
+    }
+    try:
+      payload = self.request(f"/v1/accounts/{quoted}/usageCosts:query", body=body)
+      if not isinstance(payload.get("subtotal"), dict):
+        raise FireworksError("Fireworks cost response did not include a subtotal")
+      return money_value(payload.get("subtotal"))
+    except FireworksError:
+      parsed_end = datetime.fromisoformat(end_at.replace("Z", "+00:00"))
+      summary_end = (parsed_end.date() + timedelta(days=1)).isoformat() + "T00:00:00Z"
+      payload = self.request(
+        f"/v1/accounts/{quoted}/billing/summary",
+        query={"startTime": start_at, "endTime": summary_end},
+      )
+      return sum(
+        (money_value(item.get("totalCost")) for item in payload.get("lineItems", []) if isinstance(item, dict)),
+        Decimal("0"),
+      )
+
+
+def live_balance(client: FireworksClient, account_id: str) -> Decimal | None:
+  # accounts/{id}:getBalance exists but is permission-gated: keys without the
+  # billing role get PERMISSION_DENIED, and then the configured estimate below
+  # is the best we can do. The response shape is undocumented, so accept a
+  # Money object at the top level or under any plausible field name.
+  quoted = urllib.parse.quote(normalize_account_id(account_id), safe="")
+  try:
+    payload = client.request(f"/v1/accounts/{quoted}:getBalance")
+  except FireworksError:
+    return None
+  candidates = [payload] + [payload.get(field) for field in ("balance", "creditBalance", "prepaidBalance", "amount")]
+  for value in candidates:
+    if isinstance(value, dict) and ("units" in value or "nanos" in value):
+      return money_value(value)
+  return None
+
+
+def estimated_balance(
+  client: FireworksClient,
+  account_id: str,
+  account: dict[str, Any],
+  config: dict[str, Any],
+) -> dict[str, Any] | None:
+  try:
+    funded = Decimal(str(config.get("fundedAmount") or "0"))
+  except InvalidOperation:
+    raise FireworksError("Fireworks fundedAmount must be a number")
+  if not funded.is_finite():
+    raise FireworksError("Fireworks fundedAmount must be a finite number")
+  if funded <= 0:
+    return None
+
+  funded_at = iso_timestamp(str(config.get("fundedAt") or ""))
+  if not funded_at:
+    if not account:
+      account = client.account(account_id)
+    funded_at = iso_timestamp(str(account.get("createTime") or ""))
+  if not funded_at:
+    raise FireworksError("Set fundedAt because the Fireworks account creation date is unavailable")
+
+  end_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+  spent = max(Decimal("0"), client.spent(account_id, funded_at, end_at))
+  return {
+    "remaining": float(max(Decimal("0"), funded - spent)),
+    "funded": float(funded),
+    "spent": float(spent),
+    "currency": "USD",
+    "estimated": True,
+  }
+
+
+def scan(api_base_url: str, auth_path: Path) -> dict[str, Any]:
+  config = read_config()
+  api_key, account_id = credentials(auth_path, config)
+  if not api_key:
+    return base_record(usageStatusText="Fireworks unavailable", authHelpText=AUTH_HELP)
+
+  client = FireworksClient(api_key, api_base_url)
+  account: dict[str, Any] = {}
+  if account_id:
+    account_id = normalize_account_id(account_id)
+  else:
+    account_id, account = client.discover_account()
+
+  today = datetime.now().astimezone().date()
+  usage = client.usage(account_id, today - timedelta(days=29), today + timedelta(days=1))
+  record = base_record(ready=True, hasLocalStats=True)
+  record.update(summarize_usage(usage, today))
+
+  live = live_balance(client, account_id)
+  if live is not None:
+    try:
+      funded = Decimal(str(config.get("fundedAmount") or "0"))
+      if not funded.is_finite() or funded < 0:
+        funded = Decimal("0")
+    except InvalidOperation:
+      funded = Decimal("0")
+    record["balance"] = {
+      "remaining": float(live),
+      "funded": float(funded),
+      "spent": float(max(Decimal("0"), funded - live)),
+      "currency": "USD",
+      "estimated": False,
+    }
+    return record
+
+  try:
+    balance = estimated_balance(client, account_id, account, config)
+    if balance:
+      record["balance"] = balance
+  except FireworksError as error:
+    record["usageStatusText"] = "Balance unavailable"
+    record["authHelpText"] = str(error)
+
+  return record
+
+
+def main() -> int:
+  parser = argparse.ArgumentParser(description="Print the Fireworks usage record as JSON")
+  # Stats and balance come from the same few API calls, so there is no cache
+  # to force past and no faster limits-only path. The flags exist so every
+  # collector accepts the same invocation.
+  parser.add_argument("--force", action="store_true")
+  parser.add_argument("--limits-only", action="store_true")
+  parser.add_argument("--auth-path", default=os.environ.get("FIREWORKS_AUTH_PATH", "~/.fireworks/auth.ini"))
+  parser.add_argument("--api-base-url", default=os.environ.get("FIREWORKS_API_BASE_URL", API_BASE_URL))
+  args = parser.parse_args()
+
+  try:
+    record = scan(args.api_base_url, Path(args.auth_path).expanduser())
+  except FireworksError as error:
+    record = base_record(usageStatusText="Fireworks unavailable", authHelpText=str(error))
+  except Exception as error:
+    record = base_record(usageStatusText="Fireworks unavailable", authHelpText="Fireworks usage scan failed")
+    print(f"omarchy-agent-usage-fireworks: {type(error).__name__}", file=sys.stderr)
+  print(json.dumps(record, separators=(",", ":")))
+  return 0
+
+
+if __name__ == "__main__":
+  raise SystemExit(main())

bin/omarchy-agent-usage-grok

@@ -0,0 +1,361 @@
+#!/usr/bin/python3
+# omarchy:summary=Print the Grok usage record as JSON
+# omarchy:args=[--force] [--limits-only]
+# omarchy:hidden=true
+"""Collect Grok usage into one display-ready JSON record.
+
+The plan comes from the settings Grok caches from xAI, and the limit from the
+credits endpoint the Grok CLI itself reads for its /usage view, asked with
+each account's own sign-in. Sessions come from the summary Grok keeps beside
+each session, and tokens and prompts from its usage.json, the ledger `grok
+usage` prints: one entry per finished turn, with when it ended and its tokens
+by model. The agents panel only ever reads the JSON this prints.
+"""
+
+import argparse
+import json
+import os
+import re
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+AGENT_ID = "grok"
+AGENT_NAME = "Grok"
+AUTH_HELP = "Start Grok, or run `grok login`, to sign in."
+CREDITS_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits"
+# Grok's own CLI watches its subscription once a minute; a panel opened and
+# shut repeatedly reuses an answer for about that long.
+PROBE_REUSE_SECONDS = 60
+# Grok's docs give a saved sign-in 30 days; a refresh token older than that
+# can't renew the access token, so it no longer counts as signed in.
+REFRESH_LIFETIME_SECONDS = 30 * 24 * 3600
+# A limits-only refresh needs fresh limits, not a fresh history scan.
+LIMITS_ONLY_SCAN_REUSE_SECONDS = 900
+
+
+def read_json(path):
+  try:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+  except Exception:
+    return None
+
+
+# A temporary file of its own per write, so overlapping runs can't rename
+# each other's away.
+def write_json(path, payload):
+  path = Path(path)
+  path.parent.mkdir(parents=True, exist_ok=True)
+  fd, tmp = tempfile.mkstemp(prefix=path.name + ".", dir=str(path.parent))
+  try:
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+      json.dump(payload, handle)
+    os.replace(tmp, path)
+  except Exception:
+    Path(tmp).unlink(missing_ok=True)
+    raise
+
+
+def cache_root():
+  return Path(os.environ.get("XDG_CACHE_HOME") or (Path.home() / ".cache")) / "omarchy" / "agent-usage"
+
+
+def parse_time(value):
+  try:
+    parsed = datetime.fromisoformat(str(value or "").replace("Z", "+00:00"))
+  except ValueError:
+    return None
+  return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+# The home Grok uses when nothing selects an account: GROK_HOME when set,
+# as the CLI itself reads it, else ~/.grok.
+def default_home():
+  return Path(os.environ.get("GROK_HOME") or (Path.home() / ".grok"))
+
+
+# Every session under <home>/sessions/<folder>/<session>/: its summary says
+# when it was last active and how many prompts it had, and its usage.json
+# lists each finished turn with its tokens by model. Added accounts link
+# their sessions to the primary's, so this covers all of them. Grok counts
+# cached input inside inputTokens; the record keeps the two apart, as the
+# other collectors do.
+def local_stats(home):
+  now = datetime.now().astimezone()
+  today = now.date().isoformat()
+  week = [(now.date() - timedelta(days=offset)).isoformat() for offset in range(6, -1, -1)]
+  prompts = sessions = today_sessions = today_prompts = today_tokens = 0
+  days = set()
+  by_day = {day: 0 for day in week}
+  today_by_model = {}
+  models = {}
+  for session in (Path(home) / "sessions").glob("*/*/"):
+    summary = read_json(session / "summary.json")
+    if isinstance(summary, dict):
+      active = parse_time(summary.get("last_active_at"))
+      if active:
+        day = active.astimezone().date().isoformat()
+        sessions += 1
+        prompts += int(summary.get("num_messages") or 0)
+        days.add(day)
+        if day == today:
+          today_sessions += 1
+
+    usage = read_json(session / "usage.json")
+    turns = usage.get("turns") if isinstance(usage, dict) else None
+    for turn in turns if isinstance(turns, list) else []:
+      ended = parse_time(turn.get("endedAt")) if isinstance(turn, dict) else None
+      if not ended:
+        continue
+      day = ended.astimezone().date().isoformat()
+      days.add(day)
+      if day == today:
+        today_prompts += 1
+      for model, bucket in (turn.get("modelUsage") or {}).items():
+        if not isinstance(bucket, dict):
+          continue
+        # Grok's totalTokens leaves cache writes out; counting them here keeps
+        # the day's total equal to the sum of its model's buckets.
+        cached = int(bucket.get("cachedReadTokens") or 0)
+        uncached = max(0, int(bucket.get("inputTokens") or 0) - cached)
+        output = int(bucket.get("outputTokens") or 0)
+        created = int(bucket.get("cacheCreationTokens") or 0)
+        tokens = uncached + cached + output + created
+        totals = models.setdefault(model, {"inputTokens": 0, "outputTokens": 0, "cacheReadInputTokens": 0, "cacheCreationInputTokens": 0})
+        totals["inputTokens"] += uncached
+        totals["outputTokens"] += output
+        totals["cacheReadInputTokens"] += cached
+        totals["cacheCreationInputTokens"] += created
+        if day in by_day:
+          by_day[day] += tokens
+        if day == today:
+          today_tokens += tokens
+          today_by_model[model] = today_by_model.get(model, 0) + tokens
+
+  return {
+    "hasLocalStats": sessions > 0,
+    "todayPrompts": today_prompts,
+    "todaySessions": today_sessions,
+    "todayTotalTokens": today_tokens,
+    "todayTokensByModel": today_by_model,
+    "recentDays": [{"date": day, "messageCount": by_day[day]} for day in week],
+    "totalPrompts": prompts,
+    "totalSessions": sessions,
+    "activeDays": len(days),
+    "activeDates": sorted(days),
+    "modelUsage": models,
+  }
+
+
+# A scan from before midnight would count yesterday's sessions as today's.
+def cached_local_stats(home, max_age):
+  cache = cache_root() / "grok-stats.json"
+  cached = read_json(cache) or {}
+  today = datetime.now().astimezone().date().isoformat()
+  if cached.get("home") == str(home) and cached.get("day") == today and time.time() - float(cached.get("at") or 0) < max_age:
+    return cached["stats"]
+  stats = local_stats(home)
+  write_json(cache, {"home": str(home), "day": today, "at": time.time(), "stats": stats})
+  return stats
+
+
+# One login per issuer in auth.json; the first is the CLI's own.
+def login(home):
+  auth = read_json(Path(home) / "auth.json")
+  if not isinstance(auth, dict):
+    return {}
+  return next((v for v in auth.values() if isinstance(v, dict)), {})
+
+
+def plan(home):
+  cached = read_json(Path(home) / "settings_cache.json") or {}
+  try:
+    settings = json.loads(cached.get("payload") or "{}").get("settings") or {}
+  except Exception:
+    return ""
+  return str(settings.get("subscription_tier_display") or "")
+
+
+# The credits answer as one limit window: how much of this period's included
+# usage is gone, and when the period ends. The answer is protobuf JSON, which
+# leaves out a field holding zero, so a period with nothing used yet has no
+# percentage at all.
+def credits_limit(data):
+  config = data["config"]
+  period = config["currentPeriod"]
+  return {
+    "label": "Weekly" if "WEEK" in str(period.get("type")) else "Monthly",
+    "percent": max(0.0, min(1.0, float(config.get("creditUsagePercent") or 0) / 100)),
+    "resetsAt": parse_time(period["end"]).isoformat(),
+  }
+
+
+# A window whose reset has passed starts over empty. A weekly one's next
+# reset is a whole number of weeks later; a monthly one's isn't known.
+def rolled_forward(limits):
+  now = datetime.now(timezone.utc)
+  rolled = []
+  for limit in limits:
+    resets = parse_time(limit.get("resetsAt"))
+    if resets and resets <= now:
+      limit = dict(limit, percent=0.0, resetsAt="")
+      if limit.get("label") == "Weekly":
+        weeks = (now - resets) // timedelta(weeks=1) + 1
+        limit["resetsAt"] = (resets + weeks * timedelta(weeks=1)).isoformat()
+    rolled.append(limit)
+  return rolled
+
+
+def collect_limits(home, key, force):
+  result = {"limits": [], "usageStatusText": "", "authHelpText": AUTH_HELP, "live": False, "fetchedAtMs": 0}
+  entry = login(home)
+  token = str(entry.get("key") or "")
+  if not token:
+    result["usageStatusText"] = "Waiting for auth"
+    return result
+
+  cache = cache_root() / f"grok-limits-{key}.json"
+  cached = read_json(cache) or {}
+  fetched_at = float(cached.get("fetchedAtMs") or 0)
+  result["fetchedAtMs"] = fetched_at
+
+  expires = parse_time(entry.get("expires_at"))
+  if expires and expires.timestamp() <= time.time():
+    result["limits"] = cached.get("limits") or []
+    # The access token lives six hours and Grok mints a new one from its
+    # refresh token whenever it starts, so a lapsed one is routine, not a
+    # sign-out. And while Grok hasn't run, nothing here has spent its
+    # allowance, so the last numbers still stand, rolled past any reset.
+    if entry.get("refresh_token") and time.time() - expires.timestamp() < REFRESH_LIFETIME_SECONDS:
+      result.update(limits=rolled_forward(result["limits"]), live=True)
+      if not result["limits"]:
+        result["usageStatusText"] = "Limits paused"
+        result["authHelpText"] = "Start Grok to see its limits; signing in again is not needed."
+    else:
+      result["usageStatusText"] = "Sign-in expired"
+      result["authHelpText"] = "Grok's saved sign-in expired. Start Grok to refresh it."
+    return result
+
+  if cached.get("limits") and not force and time.time() - fetched_at / 1000 < PROBE_REUSE_SECONDS:
+    result.update(limits=cached["limits"], live=True, authHelpText="")
+    return result
+
+  request = urllib.request.Request(CREDITS_URL, headers={"Authorization": f"Bearer {token}", "Accept": "application/json"})
+  try:
+    with urllib.request.urlopen(request, timeout=8) as response:
+      limit = credits_limit(json.loads(response.read()))
+  except urllib.error.HTTPError as error:
+    limit = None
+    if error.code in (401, 403):
+      result["usageStatusText"] = "Waiting for auth"
+  except Exception:
+    limit = None
+
+  if limit:
+    result.update(limits=[limit], live=True, fetchedAtMs=round(time.time() * 1000), authHelpText="")
+    write_json(cache, {"fetchedAtMs": result["fetchedAtMs"], "limits": result["limits"]})
+  else:
+    result["limits"] = cached.get("limits") or []
+    if not result["usageStatusText"] and not result["limits"]:
+      result["usageStatusText"] = "Grok limits unavailable"
+  return result
+
+
+# The accounts `omarchy agent account` registered, read straight from its
+# registry. Only a registry holding a second account matters: with one, the
+# record describes ~/.grok alone.
+def registered_accounts():
+  state = Path(os.environ.get("XDG_STATE_HOME") or (Path.home() / ".local" / "state"))
+  registry = read_json(state / "omarchy" / "agents" / "accounts" / "grok.json") or {}
+  accounts = [a for a in registry.get("accounts") or [] if isinstance(a, dict) and a.get("id")]
+  if len(accounts) < 2:
+    return []
+  active_id = registry.get("active") or accounts[0]["id"]
+  if not any(a["id"] == active_id for a in accounts):
+    active_id = accounts[0]["id"]
+  for account in accounts:
+    account["active"] = account["id"] == active_id
+    account["switch"] = {
+      "mode": "auto" if registry.get("switch") == "auto" else "manual",
+      "threshold": registry.get("threshold") or 95,
+    }
+  return accounts
+
+
+def home_of(account):
+  return Path(account.get("home") or (Path.home() / ".grok"))
+
+
+# Keyed by who the home is signed in as, so a home signed in to someone else
+# never shows the last one's numbers.
+def cache_key(home, fallback):
+  user = str(login(home).get("user_id") or "")
+  return re.sub(r"[^A-Za-z0-9_-]", "", user) or fallback
+
+
+def account_limits(account, force):
+  home = home_of(account)
+  limits = collect_limits(home, cache_key(home, account["id"]), force)
+  return {
+    "id": account["id"],
+    "label": str(account.get("label") or account["id"]),
+    "email": str(account.get("email") or ""),
+    "plan": plan(home) or str(account.get("plan") or ""),
+    "active": account["active"],
+    "primary": bool(account.get("primary")),
+    "limits": limits["limits"],
+    "stale": not limits["live"],
+    "fetchedAt": limits["fetchedAtMs"],
+    "usageStatusText": limits["usageStatusText"],
+    "authHelpText": limits["authHelpText"],
+  }
+
+
+def main():
+  parser = argparse.ArgumentParser()
+  parser.add_argument("--force", action="store_true")
+  parser.add_argument("--limits-only", action="store_true")
+  args = parser.parse_args()
+
+  registered = registered_accounts()
+  accounts = [account_limits(account, args.force) for account in registered]
+  current = next((a for a in accounts if a["active"]), None)
+  if current:
+    tier = current["plan"]
+    limits = current
+    stale, fetched_at = current["stale"], current["fetchedAt"]
+  else:
+    home = default_home()
+    tier = plan(home)
+    limits = collect_limits(home, cache_key(home, "main"), args.force)
+    stale, fetched_at = not limits["live"], limits["fetchedAtMs"]
+
+  # Nobody signed in to Grok here: an empty record, which the panel skips.
+  # With accounts registered, the primary is ~/.grok by definition.
+  stats_home = Path.home() / ".grok" if accounts else default_home()
+  signed_in = bool(accounts) or bool(login(stats_home))
+  record = {
+    "schemaVersion": 1,
+    "id": AGENT_ID,
+    "name": AGENT_NAME,
+    "updatedAt": datetime.now(timezone.utc).isoformat(),
+    "ready": signed_in,
+    "tierLabel": tier,
+    "usageStatusText": limits["usageStatusText"],
+    "authHelpText": limits["authHelpText"],
+    "limits": limits["limits"],
+    "limitsStale": stale,
+    "limitsFetchedAt": fetched_at,
+  }
+  record.update(cached_local_stats(stats_home, LIMITS_ONLY_SCAN_REUSE_SECONDS if args.limits_only and not args.force else 0))
+  if accounts:
+    record["accountSwitch"] = registered[0]["switch"]
+    record["accounts"] = accounts
+  print(json.dumps(record, separators=(",", ":")))
+
+
+if __name__ == "__main__":
+  main()

bin/omarchy-agent-usage-update

@@ -0,0 +1,89 @@
+#!/bin/bash
+
+# omarchy:summary=Regenerate the AI agent usage data files
+# omarchy:args=[--force] [--limits-only] [--except <agent>] [agent...]
+# omarchy:examples=omarchy agent usage-update | omarchy agent usage-update claude | omarchy agent usage-update --except codex
+
+# Each omarchy-agent-usage-<agent> collector prints one display-ready JSON
+# record; this writes them to ~/.local/state/omarchy/agents/usage/ where the
+# agents panel watches them. Adding an agent is adding a collector — the
+# panel picks up any record that appears here.
+
+USAGE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/agents/usage"
+mkdir -p "$USAGE_DIR"
+
+flags=()
+only=()
+declare -A excluded
+
+while (( $# > 0 )); do
+  case "$1" in
+  --force | --limits-only) flags+=("$1") ;;
+  --except)
+    excluded[$2]=1
+    shift
+    ;;
+  *) only+=("$1") ;;
+  esac
+  shift
+done
+
+wanted() {
+  local agent="$1"
+  [[ -n ${excluded[$agent]} ]] && return 1
+  (( ${#only[@]} == 0 )) && return 0
+  local candidate
+  for candidate in "${only[@]}"; do
+    [[ $candidate == "$agent" ]] && return 0
+  done
+  return 1
+}
+
+collect() {
+  local collector="$1" agent="$2"
+  local record tmp
+  if ! record=$("$collector" "${flags[@]}") || [[ -z $record ]] || ! jq -e . >/dev/null 2>&1 <<<"$record"; then
+    echo "omarchy-agent-usage-update: $agent collector failed" >&2
+    return 1
+  fi
+  tmp=$(mktemp "$USAGE_DIR/.$agent.XXXXXX")
+  printf '%s\n' "$record" >"$tmp"
+  mv "$tmp" "$USAGE_DIR/$agent.json"
+}
+
+# Accounts can be signed in to someone else since they were added; the
+# records name them from the registry, so bring it up to date first.
+accounts_dir="${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/agents/accounts"
+if [[ -f $accounts_dir/claude.json || -f $accounts_dir/codex.json || -f $accounts_dir/grok.json ]]; then
+  "$OMARCHY_PATH/bin/omarchy-agent-account-state" refresh
+fi
+
+pids=()
+for collector in "$OMARCHY_PATH"/bin/omarchy-agent-usage-*; do
+  [[ -x $collector ]] || continue
+  agent="${collector##*/omarchy-agent-usage-}"
+  [[ $agent == "update" ]] && continue
+  wanted "$agent" || continue
+  collect "$collector" "$agent" &
+  pids+=($!)
+done
+
+status=0
+for pid in "${pids[@]}"; do
+  wait "$pid" || status=1
+done
+
+# Fresh limits are when switching accounts near a limit gets decided. A switch
+# changes which account the record's own limits describe, so that record is
+# collected once more; the limits probes it repeats are still cached.
+for agent in claude codex grok; do
+  if wanted "$agent" && [[ -f $accounts_dir/$agent.json ]]; then
+    switched=$("$OMARCHY_PATH/bin/omarchy-agent-account-state" autoswitch "$agent")
+    if [[ -n $switched ]]; then
+      flags=(--limits-only)
+      collect "$OMARCHY_PATH/bin/omarchy-agent-usage-$agent" "$agent" || status=1
+    fi
+  fi
+done
+
+exit $status

bin/omarchy-apply-hardware

@@ -0,0 +1,89 @@
+#!/bin/bash
+
+# omarchy:summary=Apply Omarchy hardware-specific packages and system configuration
+# omarchy:group=apply
+# omarchy:requires-sudo=true
+# omarchy:examples=omarchy apply hardware --install-user dhh
+# omarchy:hidden=true
+
+set -euo pipefail
+
+usage() {
+  cat <<USAGE
+Usage: omarchy apply hardware --install-user USER
+       omarchy apply hardware --defer-provisioning
+
+Runs idempotent hardware detection/setup for the installed machine. This is
+called by omarchy-apply-system during ISO finalization and can be rerun later
+for diagnostics or after hardware/package updates.
+
+--defer-provisioning runs without an install user (deferred-provisioning installs create the user at
+first boot); group grants are recorded in /var/lib/omarchy/provisioning/groups.
+
+In an image build (/var/lib/omarchy/image/target exists) nothing runs here: every step is queued
+for omarchy-provision-hardware on the machine's first boot.
+USAGE
+}
+
+install_user="${OMARCHY_INSTALL_USER:-}"
+defer_provisioning=0
+while (($#)); do
+  case "$1" in
+    --install-user)
+      install_user="${2:-}"
+      shift 2
+      ;;
+    --defer-provisioning)
+      defer_provisioning=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if (( EUID != 0 )); then
+  echo "Error: omarchy-apply-hardware must run as root" >&2
+  exit 1
+fi
+
+if (( defer_provisioning )); then
+  install_user=""
+else
+  if [[ -z $install_user || $install_user == "root" ]]; then
+    echo "Error: --install-user must name the target non-root user" >&2
+    exit 1
+  fi
+
+  if ! getent passwd "$install_user" >/dev/null; then
+    echo "Error: user '$install_user' does not exist" >&2
+    exit 1
+  fi
+fi
+
+export OMARCHY_INSTALL_USER="$install_user"
+# Only omarchy-provision-hardware runs steps as an image's first boot.
+unset OMARCHY_IMAGE_DEFERRED_HARDWARE
+export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
+export OMARCHY_INSTALL="${OMARCHY_INSTALL:-$OMARCHY_PATH/install}"
+export OMARCHY_INSTALL_LOG_FILE="${OMARCHY_INSTALL_LOG_FILE:-/var/log/omarchy-install.log}"
+export PATH="$OMARCHY_PATH/bin:$PATH"
+
+source "$OMARCHY_INSTALL/helpers/logging.sh"
+source "$OMARCHY_INSTALL/helpers/image-target.sh"
+
+omarchy_image_init
+omarchy_image_lock
+if omarchy_image_manifest_present; then
+  omarchy_image_read_manifest
+  omarchy_image_defer_hardware
+else
+  source "$OMARCHY_INSTALL/hardware/all.sh"
+fi

bin/omarchy-apply-lock

@@ -0,0 +1,85 @@
+#!/bin/bash
+
+# omarchy:summary=Configure Quickshell lock screen authentication
+# omarchy:requires-sudo=true
+# omarchy:hidden=true
+
+set -e
+
+# Install and upgrade callers can start this helper as root. Ignore their PATH
+# so optional commands never fall through to a user-writable directory.
+if (( EUID == 0 )); then
+  export PATH=/usr/share/omarchy/bin:/usr/local/bin:/usr/bin:/bin
+fi
+
+target_user=${OMARCHY_INSTALL_USER:-${SUDO_USER:-}}
+if [[ -z $target_user && -n ${PKEXEC_UID:-} ]]; then
+  target_user=$(getent passwd "$PKEXEC_UID" | cut -d: -f1)
+fi
+target_user=${target_user:-$USER}
+
+as_root() {
+  if (( EUID == 0 )); then
+    "$@"
+  else
+    sudo "$@"
+  fi
+}
+
+echo "Configuring lock screen password authentication..."
+
+as_root tee /etc/pam.d/omarchy-lock-password >/dev/null <<'EOF'
+#%PAM-1.0
+auth       required                    pam_faillock.so preauth silent deny=10 unlock_time=120
+-auth      [success=2 default=ignore]  pam_systemd_home.so
+auth       [success=1 default=bad]     pam_unix.so try_first_pass nullok
+auth       [default=die]               pam_faillock.so authfail deny=10 unlock_time=120
+auth       optional                    pam_permit.so
+auth       required                    pam_env.so
+auth       required                    pam_faillock.so authsucc
+account    include                     system-local-login
+EOF
+
+# Install resume recovery alongside fingerprint PAM, so setup and upgrades
+# cannot leave one configured without the other.
+resume_hook_src="$OMARCHY_PATH/default/systemd/system-sleep/fprintd-resume"
+resume_hook_dst=/usr/lib/systemd/system-sleep/fprintd-resume
+stop_timeout_src="$OMARCHY_PATH/default/systemd/system/fprintd.service.d/10-stop-timeout.conf"
+stop_timeout_dst=/etc/systemd/system/fprintd.service.d/10-stop-timeout.conf
+
+# Keep the privileged probe pinned to /usr/bin; failure is not empty enrollment.
+if [[ -x /usr/bin/fprintd-list ]]; then
+  fingerprint_status=$(/usr/bin/fprintd-list "$target_user" 2>&1 || true)
+else
+  fingerprint_status="no"
+fi
+
+if grep -qE '^[[:space:]]*-[[:space:]]*#[0-9]+:' <<< "$fingerprint_status"; then
+  echo "Configuring lock screen fingerprint authentication..."
+  as_root install -Dm755 -o root -g root "$resume_hook_src" "$resume_hook_dst"
+  as_root install -Dm644 -o root -g root "$stop_timeout_src" "$stop_timeout_dst"
+  as_root systemctl daemon-reload
+  as_root tee /etc/pam.d/omarchy-lock-fingerprint >/dev/null <<'EOF'
+#%PAM-1.0
+auth       required                    pam_fprintd.so
+account    include                     system-local-login
+EOF
+elif [[ $fingerprint_status == "no" ]] || grep -qi 'has no fingers enrolled' <<< "$fingerprint_status"; then
+  as_root rm -f /etc/pam.d/omarchy-lock-fingerprint "$resume_hook_dst"
+  # Only reload when something was there: this branch also runs in the
+  # install chroot, where there is no systemd to reload.
+  if [[ -e $stop_timeout_dst ]]; then
+    as_root rm -f "$stop_timeout_dst"
+    as_root rmdir --ignore-fail-on-non-empty "$(dirname "$stop_timeout_dst")"
+    as_root systemctl daemon-reload
+  fi
+else
+  echo "Could not check fingerprint enrollment; keeping the existing configuration." >&2
+fi
+
+# omarchy-shell can't reach a running shell during chroot install. The echo
+# is just confirmation, so swallow the failure rather than letting it become
+# the script's exit code.
+if omarchy-shell lock status >/dev/null 2>&1; then
+  echo "Lock screen authentication configured."
+fi

bin/omarchy-apply-pacman

@@ -0,0 +1,77 @@
+#!/bin/bash
+
+# omarchy:summary=Restore channel and regional pacman defaults in an installed target
+# omarchy:args=<stable|rc|edge> [target-root] | --render <stable|rc|edge> <output-dir> [target-root]
+# omarchy:requires-sudo=true
+# omarchy:hidden=true
+
+set -euo pipefail
+
+usage() {
+  echo "Usage: omarchy-apply-pacman <stable|rc|edge> [target-root]" >&2
+  echo "       omarchy-apply-pacman --render <stable|rc|edge> <output-dir> [target-root]" >&2
+  exit 1
+}
+
+# --render only builds the two files, so an unprivileged caller can hand root
+# nothing but plain copies of the finished result.
+render_dir=""
+if [[ ${1:-} == "--render" ]]; then
+  (( $# == 3 || $# == 4 )) || usage
+  channel="$2"
+  render_dir="$3"
+  [[ -d $render_dir ]] || { echo "Render directory not found: $render_dir" >&2; exit 1; }
+  etc="${4:-/}/etc"
+else
+  (( $# >= 1 && $# <= 2 )) || usage
+  channel="$1"
+  etc="${2:-/}/etc"
+fi
+
+case "$channel" in
+  stable|rc|edge) ;;
+  *) echo "Invalid pacman channel: $channel" >&2; exit 1 ;;
+esac
+
+# The ISO writes this plain-text marker before target finalization. Missing
+# markers keep existing installations global; never source it as shell code.
+region=global
+if [[ -e $etc/omarchy/region ]]; then
+  region=$(<"$etc/omarchy/region")
+fi
+case "$region" in
+  global|cn) ;;
+  *) echo "Unsupported region: $region (expected global or cn)" >&2; exit 1 ;;
+esac
+
+# Build both files before replacing either. Explicit refreshes retain backups;
+# ordinary updates do not call this command or enforce regional defaults.
+if [[ -n $render_dir ]]; then
+  staging="$render_dir"
+else
+  staging=$(mktemp -d)
+  trap 'rm -rf "$staging"' EXIT
+fi
+cp "$OMARCHY_PATH/default/pacman/pacman-$channel.conf" "$staging/pacman.conf"
+if [[ $region == "global" ]]; then
+  cp "$OMARCHY_PATH/default/pacman/mirrorlist-$channel" "$staging/mirrorlist"
+else
+  profile="$OMARCHY_PATH/default/regions/$region/pacman"
+  printf '\n' >> "$staging/pacman.conf"
+  cat "$profile/pacman.conf.append" >> "$staging/pacman.conf"
+  # pacman tries servers in order, so the regional mirror leads and the
+  # channel's own mirror stays as the fallback.
+  cat "$profile/mirrorlist-$channel.prepend" "$OMARCHY_PATH/default/pacman/mirrorlist-$channel" > "$staging/mirrorlist"
+fi
+
+if [[ -z $render_dir ]]; then
+  mkdir -p "$etc/pacman.d"
+  for file in pacman.conf pacman.d/mirrorlist; do
+    if [[ -e $etc/$file ]]; then
+      cp -f "$etc/$file" "$etc/$file.bak"
+    fi
+  done
+  # Copying over an existing file keeps its owner and mode, as refresh always has.
+  cp -f "$staging/pacman.conf" "$etc/pacman.conf"
+  cp -f "$staging/mirrorlist" "$etc/pacman.d/mirrorlist"
+fi

bin/omarchy-apply-system

@@ -0,0 +1,102 @@
+#!/bin/bash
+
+# omarchy:summary=Apply Omarchy system setup in the installed target
+# omarchy:group=apply
+# omarchy:requires-sudo=true
+# omarchy:examples=omarchy apply system --install-user dhh --first-install
+# omarchy:hidden=true
+
+set -euo pipefail
+
+usage() {
+  cat <<USAGE
+Usage: omarchy apply system --install-user USER [--first-install|--upgrade]
+       omarchy apply system --defer-provisioning --first-install
+
+Runs root-owned Omarchy system setup. The ISO calls this in the target chroot
+after packages are installed and the target user exists. It also calls
+omarchy-apply-hardware, so hardware setup cannot be accidentally skipped.
+
+--defer-provisioning runs without an install user: deferred-provisioning installs create the user at
+first boot, so scripts that grant group memberships record them in
+/var/lib/omarchy/provisioning/groups instead of calling usermod.
+USAGE
+}
+
+install_user="${OMARCHY_INSTALL_USER:-}"
+first_install=0
+upgrade=0
+defer_provisioning=0
+
+while (($#)); do
+  case "$1" in
+    --install-user)
+      install_user="${2:-}"
+      shift 2
+      ;;
+    --defer-provisioning)
+      defer_provisioning=1
+      shift
+      ;;
+    --first-install)
+      first_install=1
+      shift
+      ;;
+    --upgrade)
+      upgrade=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if (( EUID != 0 )); then
+  echo "Error: omarchy-apply-system must run as root" >&2
+  exit 1
+fi
+
+if (( defer_provisioning )); then
+  install_user=""
+else
+  if [[ -z $install_user || $install_user == "root" ]]; then
+    echo "Error: --install-user must name the target non-root user" >&2
+    exit 1
+  fi
+
+  if ! getent passwd "$install_user" >/dev/null; then
+    echo "Error: user '$install_user' does not exist" >&2
+    exit 1
+  fi
+fi
+
+export OMARCHY_INSTALL_USER="$install_user"
+export OMARCHY_FIRST_INSTALL="$first_install"
+export OMARCHY_UPGRADE="$upgrade"
+export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
+export OMARCHY_INSTALL="${OMARCHY_INSTALL:-$OMARCHY_PATH/install}"
+export OMARCHY_INSTALL_LOG_FILE="${OMARCHY_INSTALL_LOG_FILE:-/var/log/omarchy-install.log}"
+export PATH="$OMARCHY_PATH/bin:$PATH"
+
+source "$OMARCHY_INSTALL/helpers/logging.sh"
+start_install_log
+
+source "$OMARCHY_INSTALL/config/all.sh"
+
+if (( defer_provisioning )); then
+  omarchy-apply-hardware --defer-provisioning
+else
+  omarchy-apply-hardware --install-user "$install_user"
+fi
+
+source "$OMARCHY_INSTALL/login/all.sh"
+source "$OMARCHY_INSTALL/post-install/all.sh"
+
+stop_install_log

bin/omarchy-audio-input-mute

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# omarchy:summary=Toggle microphone mute. Drives the hardware mic-mute LED on laptops that expose one.
+
+wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle >/dev/null
+
+if wpctl get-volume @DEFAULT_AUDIO_SOURCE@ | grep -q MUTED; then
+  omarchy-brightness-keyboard-mute on
+  omarchy-osd -i microphone-muted -m "$(omarchy-text "Microphone muted")"
+else
+  omarchy-brightness-keyboard-mute off
+  omarchy-osd -i microphone -m "$(omarchy-text "Microphone on")"
+fi

bin/omarchy-audio-input-set-default

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# omarchy:summary=Set the default audio input and move active streams
+# omarchy:args=<node-id> <source-name>
+# omarchy:examples=omarchy audio input set default 43 alsa_input.pci-0000_00_1f.3.analog-stereo
+
+node_id=${1:-}
+source_name=${2:-}
+
+if [[ -z $node_id || -z $source_name ]]; then
+  echo "Usage: omarchy-audio-input-set-default <node-id> <source-name>" >&2
+  exit 1
+fi
+
+wpctl set-default "$node_id" 2>/dev/null || true
+pactl set-default-source "$source_name" 2>/dev/null || true
+
+# A filter's own capture (the input half of a filter chain, loopback or echo
+# canceller, which PipeWire joins to its output by node.link-group) is the
+# processing, not an app: moving it would feed the filter from the new input, or
+# from its own output. pactl translates the listing, so it is read in the C
+# locale.
+LC_ALL=C pactl list source-outputs 2>/dev/null | awk '
+  /^Source Output #/ { if (id != "" && !filter) print id; id = substr($3, 2); filter = 0 }
+  /^[[:space:]]*node\.link-group = / { filter = 1 }
+  END { if (id != "" && !filter) print id }' | while read -r output; do
+  [[ -n $output ]] && pactl move-source-output "$output" "$source_name" 2>/dev/null || true
+done

bin/omarchy-audio-output-set-default

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# omarchy:summary=Set the default audio output and move active streams
+# omarchy:args=<node-id> <sink-name>
+# omarchy:examples=omarchy audio output set default 42 alsa_output.pci-0000_00_1f.3.analog-stereo
+
+node_id=${1:-}
+sink_name=${2:-}
+
+if [[ -z $node_id || -z $sink_name ]]; then
+  echo "Usage: omarchy-audio-output-set-default <node-id> <sink-name>" >&2
+  exit 1
+fi
+
+timeout 2 wpctl set-default "$node_id" 2>/dev/null || true
+timeout 2 pactl set-default-sink "$sink_name" 2>/dev/null || true
+
+# Move only real application streams. A DSP filter-chain's own output is also a
+# sink input but carries no application.name, and moving it would rewire the
+# processing itself -- onto headphones, or into its own virtual sink, which is a
+# cycle. EasyEffects' output stream must stay put for the same reason.
+timeout 2 pactl list sink-inputs 2>/dev/null | awk '
+  /^Sink Input #/ {id = substr($3, 2)}
+  /application\.name = / {
+    app = $0
+    sub(/.*application\.name = "/, "", app)
+    sub(/"$/, "", app)
+    if (app != "EasyEffects") print id
+  }' | while read -r input; do
+  [[ -n $input ]] && timeout 2 pactl move-sink-input "$input" "$sink_name" 2>/dev/null || true
+done

bin/omarchy-audio-output-sink

@@ -0,0 +1,96 @@
+#!/bin/bash
+
+# omarchy:summary=Print the sink whose volume and mute a given output really uses
+# omarchy:args=[sink-name]
+# omarchy:group=audio
+# omarchy:examples=omarchy audio output sink | omarchy audio output sink omarchy_speaker_tuning
+
+set -uo pipefail
+
+# A DSP sink -- a speaker tuning filter-chain, or EasyEffects -- can be the
+# selected output without being where loudness lives. Changing its volume alters
+# the level going *into* the processing: the display moves while the speakers do
+# not, and on a chain with a compressor or limiter the tone changes too. Resolve
+# through it to the physical sink it feeds.
+#
+# With no argument this resolves the current default output, so when headphones or
+# HDMI are selected it returns those, not the speakers a tuning happens to front.
+# Callers that need to describe some *other* output -- an output switcher naming
+# the next one in the rotation -- pass that sink explicitly.
+
+sink="${1:-$(pactl get-default-sink 2>/dev/null)}"
+
+if [[ -z $sink || $sink == alsa_output.* ]]; then
+  printf '%s\n' "$sink"
+  exit 0
+fi
+
+# A DSP sink feeds its physical output through a stream of its own; follow that
+# stream down to the sink underneath.
+downstream="$(pactl list sink-inputs 2>/dev/null |
+  awk -v virt="$sink" '
+    BEGIN {
+      output = virt
+      sub(/^effect_input\./, "effect_output.", output)
+    }
+    /^Sink Input #/ {target = ""}
+    /^[[:space:]]*Sink:/ {target = $2}
+    /node\.name = / {
+      name = $0
+      sub(/.*node\.name = "/, "", name)
+      sub(/"$/, "", name)
+      if (target != "" && (name == output || (output == virt && index(name, virt) == 1))) {selected = target; exit}
+      if (target != "" && fallback == "" && index(name, virt) == 1) fallback = target
+    }
+    /application\.name = "EasyEffects"/ {
+      if (virt == "easyeffects_sink" && target != "") {selected = target; exit}
+    }
+    END {
+      if (selected != "") print selected
+      else if (fallback != "") print fallback
+    }')"
+
+if [[ -n $downstream ]]; then
+  name="$(pactl list sinks short 2>/dev/null |
+    awk -v id="$downstream" '$1 == id {print $2; exit}')"
+  if [[ -n $name ]]; then
+    printf '%s\n' "$name"
+    exit 0
+  fi
+fi
+
+# EasyEffects 8 does not play into the physical sink through a stream of its
+# own: its output node links its ports straight to the sink's playback ports,
+# so the sink-input search above finds nothing and the keys would move the
+# EasyEffects sink -- whose volume its monitor, the input of the processing,
+# does not follow. Follow the port links instead: the first ALSA or Bluetooth
+# sink any EasyEffects output port is linked to.
+if [[ $sink == "easyeffects_sink" ]]; then
+  linked="$(pw-link -l 2>/dev/null |
+    awk '
+      /^[^ ]/ {src = $0}
+      /^[[:space:]]*\|->/ {
+        if (src ~ /^ee_/ && $2 ~ /^(alsa|bluez)_output\..*:playback_/) {
+          sub(/:playback_.*$/, "", $2); print $2; exit
+        }
+      }')"
+
+  # Idle, EasyEffects drops those links: fall back to the output device it is
+  # configured to feed, when that sink exists.
+  if [[ -z $linked ]]; then
+    configured="$(sed -n 's/^outputDevice=//p' \
+      "${XDG_CONFIG_HOME:-$HOME/.config}/easyeffects/db/easyeffectsrc" 2>/dev/null)"
+    if [[ -n $configured ]] && pactl list sinks short 2>/dev/null | awk '{print $2}' | grep -qxF -- "$configured"; then
+      linked="$configured"
+    fi
+  fi
+
+  if [[ -n $linked ]]; then
+    printf '%s\n' "$linked"
+    exit 0
+  fi
+fi
+
+# Nothing resolvable downstream -- the DSP sink may simply be idle and unlinked.
+# Fall back to the sink itself so callers still have something to act on.
+printf '%s\n' "$sink"

bin/omarchy-audio-output-switch

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# omarchy:summary=Switch between audio outputs while preserving the mute status
+
+# Skip the physical sink an active speaker tuning fronts: rotating onto it would
+# silently bypass the tuning rather than pick a different output.
+fronted=$(omarchy-audio-tuning fronted-sink 2>/dev/null || true)
+
+sinks=$(timeout 2 pactl -f json list sinks |
+  jq --arg fronted "$fronted" '[.[]
+    | select((.ports | length == 0) or ([.ports[]? | .availability != "not available"] | any))
+    | select($fronted == "" or .name != $fronted)]')
+sinks_count=$(jq 'length' <<<"$sinks")
+
+if (( sinks_count == 0 )); then
+  omarchy-osd -m "$(omarchy-text "No audio devices found")"
+  exit 1
+fi
+
+current_sink_name=$(timeout 2 pactl get-default-sink)
+current_sink_index=$(jq -r --arg name "$current_sink_name" 'map(.name) | index($name)' <<<"$sinks")
+
+if [[ $current_sink_index != "null" ]]; then
+  next_sink_index=$(((current_sink_index + 1) % sinks_count))
+else
+  next_sink_index=0
+fi
+
+next_sink=$(jq -c ".[$next_sink_index]" <<<"$sinks")
+next_sink_name=$(jq -r '.name' <<<"$next_sink")
+next_sink_description=$(jq -r '.description // .properties."device.description" // .name' <<<"$next_sink")
+# A tuning sink sits at a fixed 100% and unmuted while real loudness lives on the
+# physical sink beneath it, so read the level from whichever sink actually carries
+# it or the OSD contradicts the volume keys.
+next_sink_effective=$(omarchy-audio-output-sink "$next_sink_name")
+next_sink_volume=$(timeout 2 pactl get-sink-volume "$next_sink_effective" 2>/dev/null |
+  awk 'NR == 1 {for (i = 1; i <= NF; i++) if ($i ~ /%$/) {sub("%", "", $i); print $i; exit}}')
+[[ -n $next_sink_volume ]] || next_sink_volume=$(jq -r '.volume | to_entries[0].value.value_percent | sub("%"; "") | tonumber' <<<"$next_sink")
+if [[ $(timeout 2 pactl get-sink-mute "$next_sink_effective" 2>/dev/null) == *yes ]]; then
+  next_sink_is_muted=true
+else
+  next_sink_is_muted=false
+fi
+
+if [[ $next_sink_is_muted == "true" ]] || (( next_sink_volume == 0 )); then
+  icon_state="muted"
+elif (( next_sink_volume <= 33 )); then
+  icon_state="low"
+elif (( next_sink_volume <= 66 )); then
+  icon_state="medium"
+else
+  icon_state="high"
+fi
+
+if [[ $next_sink_name != $current_sink_name ]]; then
+  omarchy-audio-output-set-default "$(jq -r '.index' <<<"$next_sink")" "$next_sink_name"
+fi
+
+omarchy-osd -i "volume-${icon_state}" -m "$next_sink_description"

bin/omarchy-audio-output-volume

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+# omarchy:summary=Adjust output volume and show the Omarchy OSD
+# omarchy:args=<raise|lower|mute-toggle|+N|-N>
+# omarchy:examples=omarchy audio output volume raise | omarchy audio output volume lower | omarchy audio output volume mute-toggle | omarchy audio output volume +1
+
+action="${1:-}"
+
+if [[ -z $action ]]; then
+  echo "Usage: omarchy-audio-output-volume <raise|lower|mute-toggle|+N|-N>"
+  exit 1
+fi
+
+# Resolve through any DSP sink to the physical one, so the keys always move real
+# loudness and the processing always sees full-scale input. Shared with the audio
+# panel and the output switcher.
+sink="$(omarchy-audio-output-sink)"
+if [[ -z $sink ]]; then
+  echo "Could not resolve an audio sink to control." >&2
+  exit 1
+fi
+
+# pactl reports the same percentage scale wpctl does (both are the raw volume
+# over PA_VOLUME_NORM), so the OSD reads identically either way.
+volume_percent() {
+  pactl get-sink-volume "$sink" 2>/dev/null |
+    awk 'NR == 1 {
+      for (i = 1; i <= NF; i++)
+        if ($i ~ /%$/) {sub("%", "", $i); print $i; exit}
+    }'
+}
+
+volume_muted() {
+  [[ $(pactl get-sink-mute "$sink" 2>/dev/null) == *yes ]]
+}
+
+case "$action" in
+  raise) action="+5" ;;
+  lower) action="-5" ;;
+esac
+
+if [[ $action == "mute-toggle" ]]; then
+  runtime_dir="${XDG_RUNTIME_DIR:-/tmp}"
+  debounce_file="$runtime_dir/omarchy-audio-output-volume-mute-toggle.last"
+  now=$(date +%s%3N)
+  last=0
+  [[ -r $debounce_file ]] && read -r last <"$debounce_file" || true
+  if ((now - last < 250)); then
+    exit 0
+  fi
+  printf '%s\n' "$now" >"$debounce_file"
+
+  pactl set-sink-mute "$sink" toggle
+elif [[ $action =~ ^([+-])([0-9]+)$ ]]; then
+  direction="${BASH_REMATCH[1]}"
+  step="${BASH_REMATCH[2]}"
+
+  current="$(volume_percent)"
+  if [[ -z $current ]]; then
+    echo "Could not read volume for $sink." >&2
+    exit 1
+  fi
+
+  if [[ $direction == "+" ]]; then
+    next=$((current + step))
+    ((next <= 100)) || next=100
+  else
+    next=$((current - step))
+    ((next >= 0)) || next=0
+  fi
+
+  pactl set-sink-mute "$sink" 0
+  pactl set-sink-volume "$sink" "${next}%"
+else
+  echo "Unknown volume action: $action"
+  exit 1
+fi
+
+percent=$(volume_percent)
+if volume_muted || ((${percent:-0} == 0)); then
+  icon="volume-muted"
+else
+  icon="volume-high"
+fi
+
+omarchy-osd -i "$icon" -p "${percent:-0}"

bin/omarchy-audio-sink-availability

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# omarchy:summary=Print PulseAudio sink or source availability for the shell
+# omarchy:group=audio
+# omarchy:args=[sources]
+
+# With "sources", print source availability instead: a jack input such as a
+# headset microphone reports its port unavailable while nothing is plugged in.
+# pactl translates the listing ("not available" too), so it is read in the C
+# locale.
+kind=sinks
+header="Sink #"
+if [[ ${1:-} == "sources" ]]; then
+  kind=sources
+  header="Source #"
+fi
+
+# A speaker tuning is a virtual sink in front of the real speakers. Both exist
+# in the graph, but selecting the physical one would only bypass the tuning, so
+# report it unavailable and keep it out of the output list.
+fronted=""
+[[ $kind == sinks ]] && fronted="$(omarchy-audio-tuning fronted-sink 2>/dev/null || true)"
+
+LC_ALL=C pactl list "$kind" 2>/dev/null | awk -v fronted="$fronted" -v header="$header" '
+  function emit_sink() {
+    if (name == "") return
+    if (fronted != "" && name == fronted) {
+      print name "\t0"
+      return
+    }
+    print name "\t" ((port_count == 0 || available) ? 1 : 0)
+  }
+
+  index($0, header) == 1 {
+    emit_sink()
+    name = ""
+    in_ports = 0
+    port_count = 0
+    available = 0
+    next
+  }
+
+  /^[[:space:]]*Name:/ {
+    name = $2
+    next
+  }
+
+  /^[[:space:]]*Ports:$/ {
+    in_ports = 1
+    next
+  }
+
+  in_ports && /^\tActive Port:/ {
+    in_ports = 0
+    next
+  }
+
+  in_ports && /^\t\t/ {
+    port_count++
+    if ($0 !~ /not available/) available = 1
+    next
+  }
+
+  END {
+    emit_sink()
+  }
+'

bin/omarchy-audio-source-switch

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# omarchy:summary=Cycle to the next media source and transfer playback when the current source is playing
+# omarchy:args=[next|previous]
+# omarchy:examples=omarchy audio source switch | omarchy-audio-source-switch previous
+
+direction="${1:-next}"
+
+case "$direction" in
+  next)
+    omarchy-shell media sourceSwitch
+    ;;
+  previous)
+    omarchy-shell media sourceSwitchPrevious
+    ;;
+  *)
+    echo "Usage: omarchy-audio-source-switch [next|previous]" >&2
+    exit 1
+    ;;
+esac

bin/omarchy-audio-tuning

@@ -0,0 +1,357 @@
+#!/bin/bash
+
+# omarchy:summary=Manage the speaker tuning for this laptop
+# omarchy:args=<on|off|status|match|fronted-sink> [--force]
+# omarchy:group=audio
+# omarchy:examples=omarchy audio tuning status | omarchy audio tuning on | omarchy audio tuning off
+
+set -uo pipefail
+
+tunings_dir="$OMARCHY_PATH/default/audio/tunings"
+config_home="${XDG_CONFIG_HOME:-$HOME/.config}"
+
+# The tuning is hosted by its own PipeWire client, under its own config name, so
+# switching it needs no audio restart -- a restart drops every PulseAudio client's
+# connection, and applications that do not reconnect (Spotify) then have to be
+# restarted by hand. The name is deliberately not PipeWire's stock
+# filter-chain.conf, which merges every fragment in filter-chain.conf.d/ and would
+# make this service host unrelated user filters too.
+host_config_name=omarchy-speaker-tuning.conf
+host_config="$config_home/pipewire/$host_config_name"
+host_source="$OMARCHY_PATH/default/audio/filter-chain-host.conf"
+fragment="$config_home/pipewire/$host_config_name.d/90-tuning.conf"
+unit_name=omarchy-speaker-tuning.service
+unit="$config_home/systemd/user/$unit_name"
+unit_source="$OMARCHY_PATH/default/systemd/user/$unit_name"
+
+# Earlier revisions loaded the tuning into the daemon, as a WirePlumber smart
+# filter, or into the shared filter-chain.conf.d namespace. Remove all three so
+# they cannot be loaded alongside the current one.
+stale_daemon="$config_home/pipewire/pipewire.conf.d/90-omarchy-speaker-tuning.conf"
+stale_wireplumber="$config_home/wireplumber/wireplumber.conf.d/90-omarchy-speaker-tuning.conf"
+stale_shared="$config_home/pipewire/filter-chain.conf.d/90-omarchy-speaker-tuning.conf"
+
+sink_name=omarchy_speaker_tuning
+
+action="${1:-status}"
+force=0
+[[ ${2:-} == "--force" ]] && force=1
+
+sink_matching() {
+  pactl list sinks short 2>/dev/null | awk -v p="$1" '$2 ~ p {print $2; exit}'
+}
+
+# Dell keys its Cirrus speaker firmware on the DMI product SKU, which makes it the
+# most precise identifier available for these machines -- narrower than a product
+# name, and it distinguishes models whose names differ only by marketing. Compared
+# case-insensitively against an exact SKU, never a substring, so a tuning cannot
+# accidentally widen to a whole product line.
+sku_matches() {
+  local sku want
+  sku="$(cat /sys/class/dmi/id/product_sku 2>/dev/null)"
+  [[ -n $sku ]] || return 1
+  for want in "$@"; do
+    [[ ${sku,,} == "${want,,}" ]] && return 0
+  done
+  return 1
+}
+
+dmi_matches() {
+  local want
+  for want in "$@"; do
+    omarchy-hw-match "$want" 2>/dev/null && return 0
+  done
+  return 1
+}
+
+# Print the tuning directory matching this laptop, if any. Matching is data, not
+# code: a tuning declares the DMI string it belongs to and the sink it expects, so
+# most tunings can be added as a directory with no new script. A tuning whose
+# hardware needs a sharper test can set match_command to any predicate instead.
+tuning_match() {
+  local dir
+  for dir in "$tunings_dir"/*/; do
+    [[ -r $dir/tuning.conf ]] || continue
+
+    unset match_dmi match_sku match_command sink_pattern
+    # shellcheck disable=SC1090
+    source "$dir/tuning.conf"
+
+    # Deliberately does not look at the live audio graph. The install hooks run in
+    # the ISO chroot with no audio server, and a match that depended on a present
+    # sink would come back empty there -- so the machine would get neither the LV2
+    # dependency nor the tuning, and nothing would retry.
+    # A tuning may list several models it has been validated on. match_dmi and
+    # match_sku are arrays, so a plain string still works as a single entry.
+    if [[ -n ${match_command:-} ]]; then
+      "$match_command" 2>/dev/null || continue
+    elif [[ -n ${match_sku:-} ]]; then
+      sku_matches "${match_sku[@]}" || continue
+    elif [[ -n ${match_dmi:-} ]]; then
+      dmi_matches "${match_dmi[@]}" || continue
+    else
+      continue
+    fi
+
+    # Required whichever way the tuning matched: the graph's target sink is
+    # substituted from it, so a tuning without one cannot be installed and must
+    # not be reported as a match.
+    [[ -n ${sink_pattern:-} ]] || continue
+
+    printf '%s\n' "${dir%/}"
+    return 0
+  done
+  return 1
+}
+
+# The physical sink the matched tuning is built for, taken from the tuning's own
+# sink_pattern rather than a hard-coded regex, so hardware with a different sink
+# name needs no change here.
+tuned_hardware_sink() {
+  local dir found
+  dir="$(tuning_match)" || return 1
+  unset sink_pattern
+  # shellcheck disable=SC1090
+  source "$dir/tuning.conf"
+  [[ -n ${sink_pattern:-} ]] || return 1
+  found="$(sink_matching "$sink_pattern")"
+  [[ -n $found ]] || return 1
+  printf '%s\n' "$found"
+}
+
+tuning_present() {
+  pactl list sinks short 2>/dev/null | awk '{print $2}' | grep -x "$sink_name" >/dev/null
+}
+
+# Only real application streams may be moved. A filter-chain's own output is also
+# a sink input but carries no application.name, and moving it would rewire the
+# tuning itself.
+app_streams() {
+  pactl list sink-inputs 2>/dev/null | awk '
+    /^Sink Input #/ {id = substr($3, 2)}
+    /application\.name = / {
+      app = $0
+      sub(/.*application\.name = "/, "", app)
+      sub(/"$/, "", app)
+      if (app != "EasyEffects") print id
+    }'
+}
+
+move_apps_to() {
+  local target="$1" id
+  for id in $(app_streams); do
+    pactl move-sink-input "$id" "$target" 2>/dev/null || true
+  done
+}
+
+# WirePlumber can link the output elsewhere if the target is missing when the host
+# starts. node.dont-fallback guards against it, but verify rather than assume.
+tuning_downstream_sink() {
+  omarchy-audio-output-sink "$sink_name" 2>/dev/null
+}
+
+easyeffects_running() {
+  pactl list sinks short 2>/dev/null | awk '{print $2}' | grep -x easyeffects_sink >/dev/null ||
+    pgrep -u "$(id -u)" -x easyeffects >/dev/null 2>&1 ||
+    systemctl --user is-active --quiet easyeffects.service 2>/dev/null
+}
+
+# Unloading a daemon-loaded drop-in is the one case that still needs an audio
+# restart, because the daemon only reads its own config at startup.
+drop_stale_daemon_config() {
+  [[ -e $stale_daemon || -e $stale_wireplumber ]] || return 0
+  rm -f "$stale_daemon" "$stale_wireplumber"
+  omarchy-restart-audio >/dev/null 2>&1
+  local _
+  for _ in {1..40}; do
+    pactl info >/dev/null 2>&1 && break
+    sleep 0.25
+  done
+}
+
+case "$action" in
+  match)
+    tuning_match
+    ;;
+
+  fronted-sink)
+    # The tuning is a virtual sink in front of the real speakers, so both exist in
+    # the graph. Selecting the physical one would only bypass the tuning, so
+    # callers keep it out of the output list while the tuning is up. This answers
+    # "is a tuning in place", not "where should volume go" -- for the latter see
+    # omarchy-audio-output-sink, which follows the current default output.
+    tuning_present || exit 1
+    tuned_hardware_sink
+    ;;
+
+  status)
+    if [[ -r $fragment ]]; then
+      echo "Installed:    yes ($fragment)"
+    else
+      echo "Installed:    no"
+    fi
+    # Both is-active and is-enabled print their answer *and* exit non-zero when
+    # negative, so a "|| echo" fallback prints it twice.
+    host_state="$(systemctl --user is-active "$unit_name" 2>/dev/null)"
+    host_enabled="$(systemctl --user is-enabled "$unit_name" 2>/dev/null)"
+    echo "Host service: ${host_state:-inactive} (${host_enabled:-disabled})"
+    if tuning_present; then
+      echo "Tuning sink:  present"
+    else
+      echo "Tuning sink:  absent"
+    fi
+    echo "Default sink: $(pactl get-default-sink 2>/dev/null)"
+    if dir="$(tuning_match)"; then
+      unset description
+      # shellcheck disable=SC1090
+      source "$dir/tuning.conf"
+      echo "Matches:      ${description:-?} ($(basename "$dir"))"
+    else
+      echo "Matches:      nothing ships for this laptop"
+    fi
+    ;;
+
+  off)
+    if [[ ! -r $fragment && ! -r $unit && ! -r $stale_daemon && ! -r $stale_wireplumber &&
+      ! -r $stale_shared ]]; then
+      echo "No speaker tuning installed."
+      exit 0
+    fi
+
+    speakers="$(tuned_hardware_sink)" || speakers=""
+
+    systemctl --user disable --now "$unit_name" >/dev/null 2>&1
+    rm -f "$fragment" "$host_config" "$unit" "$stale_shared"
+    rmdir "$config_home/pipewire/$host_config_name.d" 2>/dev/null
+    systemctl --user daemon-reload >/dev/null 2>&1
+    drop_stale_daemon_config
+
+    for _ in {1..20}; do
+      tuning_present || break
+      sleep 0.25
+    done
+
+    if [[ -n $speakers ]]; then
+      pactl set-default-sink "$speakers" >/dev/null 2>&1
+      # Streams left on the vanished tuning sink reconnect wherever PipeWire puts
+      # them, which is not necessarily the speakers.
+      move_apps_to "$speakers"
+    fi
+    echo "Speaker tuning removed."
+    ;;
+
+  on)
+    [[ -d $tunings_dir ]] || {
+      echo "No tunings shipped at $tunings_dir" >&2
+      exit 1
+    }
+
+    selected="$(tuning_match)" || {
+      echo "No speaker tuning matches this laptop."
+      exit 0
+    }
+
+    unset description sink_pattern
+    # shellcheck disable=SC1090
+    source "$selected/tuning.conf"
+
+    # At first-run the session is up but the sink can still be settling.
+    for _ in {1..20}; do
+      speaker_sink="$(sink_matching "$sink_pattern")"
+      [[ -n $speaker_sink ]] && break
+      sleep 0.5
+    done
+    [[ -n ${speaker_sink:-} ]] || {
+      echo "A tuning applies to this laptop but no sink matching $sink_pattern" >&2
+      echo "is present, so there is no audio server yet. Re-run after login:" >&2
+      echo "  omarchy audio tuning on" >&2
+      exit 1
+    }
+
+    if easyeffects_running; then
+      cat >&2 <<'EOF'
+EasyEffects is running. It moves any stream that follows the default sink to its
+own sink, so a tuning installed now would be bypassed.
+
+Stop it first:  systemctl --user disable --now easyeffects.service
+EOF
+      exit 1
+    fi
+
+    # Every tuning ends in a limiter, which is an LV2 plugin. Without it the graph
+    # fails to instantiate and the tuning sink never appears.
+    ls /usr/lib/lv2/lsp-plugins.lv2/limiter_stereo.ttl >/dev/null 2>&1 || {
+      echo "lsp-plugins-lv2 is required for the tuning limiter." >&2
+      exit 1
+    }
+
+    rendered="$(mktemp)"
+    trap 'rm -f "$rendered"' EXIT
+    sed "s|@SPEAKER_SINK@|$speaker_sink|g" "$selected/filter-chain.conf" >"$rendered"
+
+    # Everything that makes the tuning current has to match, not just the graph:
+    # an active-but-disabled service disappears at next login, and a stale unit
+    # file would shadow later fixes to the shipped one indefinitely.
+    if ((!force)) && [[ -r $fragment ]] && cmp -s "$rendered" "$fragment" &&
+      [[ -r $host_config ]] && cmp -s "$host_source" "$host_config" &&
+      [[ -r $unit ]] && cmp -s "$unit_source" "$unit" &&
+      systemctl --user is-active --quiet "$unit_name" 2>/dev/null &&
+      systemctl --user is-enabled --quiet "$unit_name" 2>/dev/null &&
+      [[ "$(tuning_downstream_sink)" == "$speaker_sink" ]]; then
+      echo "Speaker tuning already current: $description"
+      exit 0
+    fi
+
+    drop_stale_daemon_config
+
+    rm -f "$stale_shared"
+    install -Dm644 "$host_source" "$host_config"
+    install -Dm644 "$rendered" "$fragment"
+    install -Dm644 "$unit_source" "$unit"
+    systemctl --user daemon-reload >/dev/null 2>&1
+    systemctl --user enable "$unit_name" >/dev/null 2>&1
+    systemctl --user restart "$unit_name" >/dev/null 2>&1
+    echo "Installed speaker tuning: $description"
+
+    for _ in {1..40}; do
+      tuning_present && break
+      sleep 0.25
+    done
+    if ! tuning_present; then
+      systemctl --user disable --now "$unit_name" >/dev/null 2>&1
+      rm -f "$fragment" "$host_config" "$unit"
+      systemctl --user daemon-reload >/dev/null 2>&1
+      echo "Tuning sink never appeared, so it was removed. Audio is untouched." >&2
+      echo "Check: systemctl --user status $unit_name" >&2
+      exit 1
+    fi
+
+    # Confirm the output really landed on the sink this tuning was measured for.
+    for _ in {1..20}; do
+      [[ "$(tuning_downstream_sink)" == "$speaker_sink" ]] && break
+      sleep 0.25
+    done
+    downstream="$(tuning_downstream_sink)"
+    if [[ $downstream != "$speaker_sink" ]]; then
+      systemctl --user disable --now "$unit_name" >/dev/null 2>&1
+      rm -f "$fragment" "$host_config" "$unit"
+      systemctl --user daemon-reload >/dev/null 2>&1
+      echo "The tuning output linked to ${downstream:-nothing} instead of" >&2
+      echo "$speaker_sink, so it was removed rather than left tuning the wrong" >&2
+      echo "device. Audio is untouched." >&2
+      exit 1
+    fi
+
+    pactl set-default-sink "$sink_name" >/dev/null 2>&1
+    # A default sink only captures newly created streams, so anything already
+    # playing would keep bypassing the tuning until its app was restarted.
+    move_apps_to "$sink_name"
+
+    echo "Speakers now play through the tuning."
+    ;;
+
+  *)
+    echo "Usage: omarchy-audio-tuning <on|off|status|match|fronted-sink> [--force]" >&2
+    exit 2
+    ;;
+esac

bin/omarchy-bar

@@ -0,0 +1,497 @@
+#!/bin/bash
+
+# omarchy:summary=Configure the bar and its widget layout
+# omarchy:group=bar
+# omarchy:args=use <id> | reset | defaults | position [top|bottom|left|right] | background [opaque|glassy|none|cycle] | put <id> [placement] | move <id> [placement] | set <id> <key> <value> [--json] [placement] | get <id> <key>
+# omarchy:examples=omarchy bar use local.neon-bar | omarchy bar put omarchy.keyboard-layout --after omarchy.clock | omarchy bar move omarchy.clock --section center --index 0 | omarchy bar set omarchy.clock format HH:mm
+
+set -euo pipefail
+
+source omarchy-shell-config
+
+usage() {
+  cat <<USAGE
+Usage: omarchy bar <command> [args...]
+
+  use <id>                             Use a bar option as the active bar
+  reset                                Return to the built-in Omarchy bar
+  defaults                             Restore the default bar and service widgets
+  position [top|bottom|left|right]     Bar position; prints the current one
+                                       when given none
+  background [opaque|glassy|none|cycle]
+                                       Bar background: glassy shows what is
+                                       behind the bar blurred, cycle steps
+                                       none, glassy, opaque; prints the
+                                       current one when given none
+  put <id> [placement]                 Put a widget on the bar, leaving one
+                                       that is already there where it is
+  move <id> [placement]                Move a widget within or between sections
+  set <id> <key> <value> [--json] [placement]
+                                       Set a per-widget option
+  get <id> <key>                       Print a per-widget option
+
+Placement:
+  --section <left|center|right>        Target section
+  --index <n>                          Target index
+  --before <id>                        Insert before a widget
+  --after <id>                         Insert after a widget
+  --from-section <section>             Source section
+  --from-index <n>                     Source index
+
+Enable and disable widgets with 'omarchy plugin enable' and
+'omarchy plugin disable'.
+
+'put' places a widget the way 'plugin enable' does, but leaves one that is
+already on the bar where it is, and falls back to the widget's usual spot when
+--before / --after names a widget the bar does not carry.
+
+Examples:
+  omarchy bar use local.neon-bar
+  omarchy bar put omarchy.keyboard-layout --after omarchy.clock
+  omarchy bar move omarchy.media left
+  omarchy bar move omarchy.clock --section center --index 0
+  omarchy bar set omarchy.clock format HH:mm
+USAGE
+}
+
+# ------------------------------------------------------------------ validation
+
+bar_option_exists() {
+  omarchy-plugin-catalog | jq -e --arg id "$1" '
+    any(.[]; (.kinds | index("bar")) and .barPath != null and .id == $id)
+  ' >/dev/null
+}
+
+validate_section() {
+  [[ $1 =~ ^(left|center|right)$ ]] || fail "section must be left, center, or right"
+}
+
+validate_index() {
+  [[ $1 =~ ^[0-9]+$ ]] || fail "index must be a non-negative integer"
+}
+
+# --------------------------------------------------------------------- placement
+
+PLACEMENT_SECTION=""
+PLACEMENT_INDEX=""
+PLACEMENT_BEFORE=""
+PLACEMENT_AFTER=""
+PLACEMENT_FROM_SECTION=""
+PLACEMENT_FROM_INDEX=""
+
+parse_placement() {
+  while (( $# > 0 )); do
+    case "$1" in
+      --section)
+        PLACEMENT_SECTION="${2:-}"
+        validate_section "$PLACEMENT_SECTION"
+        shift 2
+        ;;
+      --index)
+        PLACEMENT_INDEX="${2:-}"
+        validate_index "$PLACEMENT_INDEX"
+        shift 2
+        ;;
+      --before)
+        PLACEMENT_BEFORE="${2:-}"
+        [[ -n $PLACEMENT_BEFORE ]] || fail "--before requires a widget id"
+        shift 2
+        ;;
+      --after)
+        PLACEMENT_AFTER="${2:-}"
+        [[ -n $PLACEMENT_AFTER ]] || fail "--after requires a widget id"
+        shift 2
+        ;;
+      --from-section)
+        PLACEMENT_FROM_SECTION="${2:-}"
+        validate_section "$PLACEMENT_FROM_SECTION"
+        shift 2
+        ;;
+      --from-index)
+        PLACEMENT_FROM_INDEX="${2:-}"
+        validate_index "$PLACEMENT_FROM_INDEX"
+        shift 2
+        ;;
+      -h | --help)
+        usage
+        exit 0
+        ;;
+      *)
+        fail "unknown option: $1"
+        ;;
+    esac
+  done
+
+  [[ -z $PLACEMENT_BEFORE || -z $PLACEMENT_AFTER ]] || fail "use only one of --before or --after"
+}
+
+placement_json() {
+  jq -cn \
+    --arg section "$PLACEMENT_SECTION" \
+    --arg index "$PLACEMENT_INDEX" \
+    --arg before "$PLACEMENT_BEFORE" \
+    --arg after "$PLACEMENT_AFTER" \
+    --arg fromSection "$PLACEMENT_FROM_SECTION" \
+    --arg fromIndex "$PLACEMENT_FROM_INDEX" '
+      {}
+      + (if $section == "" then {} else {section: $section} end)
+      + (if $index == "" then {} else {index: ($index | tonumber)} end)
+      + (if $before == "" then {} else {before: $before} end)
+      + (if $after == "" then {} else {after: $after} end)
+      + (if $fromSection == "" then {} else {fromSection: $fromSection} end)
+      + (if $fromIndex == "" then {} else {fromIndex: ($fromIndex | tonumber)} end)
+    '
+}
+
+# -------------------------------------------------------------------- commands
+
+cmd_use() {
+  local plugin="${1:-}"
+  [[ -n $plugin ]] || fail "bar option id is required"
+  (( $# == 1 )) || fail "use takes a single bar option id"
+  if [[ $plugin == "default" || $plugin == "built-in" ]]; then
+    plugin="omarchy.bar"
+  fi
+  bar_option_exists "$plugin" || fail "$plugin is not a known bar option; run 'omarchy plugin list'"
+
+  if [[ $plugin == "omarchy.bar" ]]; then
+    commit "$NORMALIZE | del(.bar.id)"
+  else
+    commit "$NORMALIZE | .bar.id = \$plugin" --arg plugin "$plugin"
+  fi
+  echo "Using $plugin as the active bar"
+}
+
+cmd_defaults() {
+  (( $# == 0 )) || fail "defaults does not take arguments"
+
+  local optional_widgets="[]"
+  local service widget
+  for service in dropbox tailscale; do
+    if "omarchy-installed-service-$service"; then
+      widget=$(jq -cn \
+        --arg id "omarchy.$service" \
+        --arg section "$(bar_widget_default_section "omarchy.$service")" \
+        '{id: $id, section: $section}')
+      optional_widgets=$(jq -c --argjson widget "$widget" '. + [$widget]' <<<"$optional_widgets")
+    fi
+  done
+
+  # This remains one file mutation so it also works during the headless
+  # Quattro upgrade and cannot race the shell's in-memory config.
+  commit "$NORMALIZE
+    | .bar = \$defaults[0].bar
+    | def entry_id: if type == \"object\" then (.id // \"\" | tostring) else tostring end;
+      def anchor_for(\$section): { left: \"omarchy.workspaces\", center: \"omarchy.weather\", right: \"omarchy.tray\" }[\$section];
+      reduce \$widgets[] as \$widget (.;
+        .bar.layout.left = (.bar.layout.left | map(select(entry_id != \$widget.id)))
+        | .bar.layout.center = (.bar.layout.center | map(select(entry_id != \$widget.id)))
+        | .bar.layout.right = (.bar.layout.right | map(select(entry_id != \$widget.id)))
+        | (.bar.layout[\$widget.section] | map(entry_id) | index(anchor_for(\$widget.section))) as \$anchor
+        | (\$anchor | if . == null then (.bar.layout[\$widget.section] | length) else . + 1 end) as \$index
+        | .bar.layout[\$widget.section] = (
+            .bar.layout[\$widget.section][0:\$index]
+            + [{id: \$widget.id}]
+            + .bar.layout[\$widget.section][\$index:]
+          )
+      )
+  " \
+    --slurpfile defaults "$DEFAULTS_FILE" \
+    --argjson widgets "$optional_widgets"
+  sync_glass || fail "could not change the blur behind the bar"
+  echo "Restored the default Omarchy bar"
+}
+
+cmd_position() {
+  if (( $# == 0 )); then
+    jq -r '.bar.position // "top"' "$(source_file)"
+    return
+  fi
+
+  local position="$1"
+  (( $# == 1 )) || fail "position takes a single value"
+  [[ $position =~ ^(top|bottom|left|right)$ ]] || fail "position must be top, bottom, left, or right"
+  commit "$NORMALIZE | .bar.position = \$position" --arg position "$position"
+  echo "Bar position set to $position"
+}
+
+# The bar background is opaque, glassy, or none. A shell.json from before it
+# had one says transparent instead, which is none, and setting a background
+# drops it.
+current_background() {
+  jq -r '.bar.background // (if .bar.transparent == true then "none" else "opaque" end)' "$(source_file)"
+}
+
+cmd_background() {
+  if (( $# == 0 )); then
+    current_background
+    return
+  fi
+
+  local background="$1"
+  (( $# == 1 )) || fail "background takes a single value"
+  [[ $background =~ ^(opaque|glassy|none|cycle)$ ]] || fail "background must be opaque, glassy, none, or cycle"
+
+  if [[ $background == "cycle" ]]; then
+    # Each step changes the bar by one degree: clear, then glassy, then opaque.
+    case $(current_background) in
+      none) background="glassy" ;;
+      glassy) background="opaque" ;;
+      *) background="none" ;;
+    esac
+  fi
+
+  local previous
+  previous=$(current_background)
+  commit "$NORMALIZE | .bar.background = \$background | del(.bar.transparent)" --arg background "$background"
+  if ! sync_glass; then
+    commit "$NORMALIZE | .bar.background = \$background | del(.bar.transparent)" --arg background "$previous"
+    fail "could not change the blur behind the bar"
+  fi
+  echo "Bar background set to $background"
+}
+
+# The older on/off form of the background, kept for scripts and dotfiles:
+# transparent is none, and not transparent is opaque.
+cmd_transparent() {
+  local transparent="${1:-}"
+  [[ -n $transparent ]] || fail "transparent is required"
+  (( $# == 1 )) || fail "transparent takes a single value"
+  [[ $transparent =~ ^(true|false|toggle)$ ]] || fail "transparent must be true, false, or toggle"
+  if [[ $transparent == "toggle" ]]; then
+    [[ $(current_background) == "none" ]] && transparent="false" || transparent="true"
+  fi
+  if [[ $transparent == "true" ]]; then
+    cmd_background none
+  else
+    cmd_background opaque
+  fi
+}
+
+# Hyprland blurs behind the bar only while the bar-glassy toggle is on, so it
+# follows the bar background, reloading Hyprland only when it changes. The
+# toggle sits where Hyprland reads it, under XDG_STATE_HOME.
+sync_glass() {
+  local dir="${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/toggles/hypr"
+  local flag="$dir/bar-glassy.lua"
+
+  if [[ $(current_background) == "glassy" ]]; then
+    [[ ! -f $flag ]] || return 0
+    mkdir -p "$dir" && cp "$OMARCHY_PATH/default/hypr/toggles/bar-glassy.lua" "$flag" || return 1
+  else
+    [[ -f $flag ]] || return 0
+    rm -f "$flag" || return 1
+  fi
+
+  hyprctl reload >/dev/null 2>&1 || true
+}
+
+bar_widget_default_section() {
+  local catalog
+  catalog=$(omarchy-plugin-catalog 2>/dev/null) || {
+    echo "center"
+    return 0
+  }
+  jq -r --arg id "$1" '
+    map(select(.id == $id))[0].barWidget.defaultSection // "center"
+    | if IN("left", "center", "right") then . else "center" end
+  ' <<<"$catalog"
+}
+
+# Asks the shell to place a widget, waiting out one still coming up. Answers 0
+# with the reply in PUT_RESULT, 1 when there was no shell to ask. Only an
+# absent shell is carried on from: omarchy-migrate marks a 0 return as done.
+PUT_RESULT=""
+SHELL_ANSWERED=0
+ask_to_put() {
+  local id="$1" placement="$2" attempt absent=0
+  for (( attempt = 0; attempt < ${OMARCHY_SHELL_READY_ATTEMPTS:-50}; attempt++ )); do
+    if PUT_RESULT=$(omarchy-shell shell putBarWidget "$id" "$placement" 2>&1); then
+      SHELL_ANSWERED=1
+      [[ $PUT_RESULT == "not ready" ]] || return 0
+    elif [[ $PUT_RESULT == *"not ready"* ]]; then
+      SHELL_ANSWERED=1
+    elif [[ $PUT_RESULT == *"is not running"* ]]; then
+      # Answered once and now gone: it stopped mid-request.
+      if (( SHELL_ANSWERED )); then
+        fail "omarchy-shell did not become ready; $id was not put on the bar"
+      fi
+      # A shell being spawned has no socket yet, and nothing says a launch is
+      # under way, so give one a few seconds to turn up.
+      if (( ++absent >= ${OMARCHY_SHELL_ABSENT_ATTEMPTS:-30} )); then
+        echo "omarchy-shell is not running; $id was not put on the bar" >&2
+        return 1
+      fi
+    else
+      fail "could not put $id on the bar: $PUT_RESULT"
+    fi
+    sleep 0.1
+  done
+  fail "omarchy-shell did not become ready; $id was not put on the bar"
+}
+
+# Placement lives in the shell, which owns the config it has in memory. Putting
+# a widget therefore asks the shell rather than editing the file behind it.
+cmd_put() {
+  local id="${1:-}"
+  [[ -n $id ]] || fail "put requires a widget id"
+  shift
+
+  local positional_section=""
+  if (( $# > 0 )) && [[ $1 != --* ]]; then
+    positional_section="$1"
+    validate_section "$positional_section"
+    shift
+  fi
+
+  parse_placement "$@"
+  [[ -z $positional_section || -z $PLACEMENT_SECTION ]] ||
+    fail "specify a section positionally or with --section, not both"
+  [[ -z $positional_section ]] || PLACEMENT_SECTION="$positional_section"
+  [[ -z $PLACEMENT_FROM_SECTION && -z $PLACEMENT_FROM_INDEX ]] ||
+    fail "put does not accept --from-section or --from-index"
+
+  local placement
+  placement=$(placement_json)
+  ask_to_put "$id" "$placement" || return 0
+
+  # An update runs migrations before it restarts the shell, so this one can
+  # predate the fallback. Ask it again without the neighbour it cannot find.
+  if [[ $PUT_RESULT == "could not find target widget"* ]]; then
+    PLACEMENT_BEFORE=""
+    PLACEMENT_AFTER=""
+    ask_to_put "$id" "$(placement_json)" || return 0
+  fi
+
+  [[ $PUT_RESULT != "unknown" ]] || fail "$id is not a known widget; run 'omarchy plugin list'"
+  [[ $PUT_RESULT == "ok" ]] || fail "$PUT_RESULT"
+  # Says nothing about whether it had to be placed: a widget already on the bar
+  # is left where it is, and both outcomes are the same answer to the caller.
+  echo "$id is on the bar"
+}
+
+cmd_move() {
+  local id="${1:-}"
+  [[ -n $id ]] || fail "move requires a widget id"
+  shift
+
+  local positional_section=""
+  if (( $# > 0 )) && [[ $1 != --* ]]; then
+    positional_section="$1"
+    validate_section "$positional_section"
+    shift
+  fi
+
+  parse_placement "$@"
+  [[ -z $positional_section || -z $PLACEMENT_SECTION ]] ||
+    fail "specify a section positionally or with --section, not both"
+  [[ -z $positional_section || -z $PLACEMENT_INDEX ]] ||
+    fail "specify a section positionally or use --index, not both"
+  [[ -z $positional_section || -z $PLACEMENT_BEFORE ]] ||
+    fail "specify a section positionally or use --before, not both"
+  [[ -z $positional_section || -z $PLACEMENT_AFTER ]] ||
+    fail "specify a section positionally or use --after, not both"
+  [[ -z $positional_section ]] || PLACEMENT_SECTION="$positional_section"
+
+  local result
+  result=$(omarchy-shell shell moveBarWidget "$id" "$(placement_json)")
+  [[ $result == "ok" ]] || fail "$result"
+  echo "Moved $id"
+}
+
+cmd_set() {
+  local id="${1:-}"
+  local key="${2:-}"
+  local value="${3:-}"
+  [[ -n $id ]] || fail "set requires a widget id"
+  [[ -n $key ]] || fail "set requires a setting key"
+  (( $# >= 3 )) || fail "set requires a value"
+  shift 3
+
+  local value_is_json="false"
+  if (( $# > 0 )) && [[ $1 == "--json" ]]; then
+    value_is_json="true"
+    shift
+  fi
+  parse_placement "$@"
+  [[ -z $PLACEMENT_BEFORE && -z $PLACEMENT_AFTER ]] ||
+    fail "set does not accept --before or --after"
+
+  local value_json
+  if [[ $value_is_json == "true" ]]; then
+    value_json=$(jq -cn --argjson value "$value" '$value') ||
+      fail "invalid JSON value: $value"
+  else
+    value_json=$(jq -cn --arg value "$value" '$value')
+  fi
+
+  local result
+  result=$(omarchy-shell shell setBarWidget "$id" "$key" "$value_json" "$(placement_json)")
+  [[ $result == "ok" ]] || fail "$result"
+  echo "Set $key on $id"
+}
+
+# Prints the option from the first instance of the widget on the bar, raw for a
+# string and as JSON otherwise, and fails when no instance sets it.
+cmd_get() {
+  local id="${1:-}"
+  local key="${2:-}"
+  [[ -n $id ]] || fail "get requires a widget id"
+  [[ -n $key ]] || fail "get requires a setting key"
+  (( $# == 2 )) || fail "get takes a widget id and a setting key"
+
+  jq -e -r --arg id "$id" --arg key "$key" '
+    first(.bar.layout[]?[]? | select(.id == $id) | .[$key] | select(. != null))
+    | if type == "string" then . else tojson end
+  ' "$(source_file)" 2>/dev/null || exit 1
+}
+
+# --------------------------------------------------------------------- dispatch
+
+command="${1:-}"
+(( $# > 0 )) && shift || true
+
+case "$command" in
+  use)
+    cmd_use "$@"
+    ;;
+  reset)
+    (( $# == 0 )) || fail "reset does not take arguments"
+    cmd_use omarchy.bar
+    ;;
+  defaults)
+    cmd_defaults "$@"
+    ;;
+  position)
+    cmd_position "$@"
+    ;;
+  transparent)
+    cmd_transparent "$@"
+    ;;
+  background)
+    cmd_background "$@"
+    ;;
+  # Internal: the shell runs this when it loads a bar background, so one set
+  # by editing shell.json gets its blur too.
+  sync-glass)
+    sync_glass || fail "could not change the blur behind the bar"
+    ;;
+  put)
+    cmd_put "$@"
+    ;;
+  move)
+    cmd_move "$@"
+    ;;
+  set)
+    cmd_set "$@"
+    ;;
+  get)
+    cmd_get "$@"
+    ;;
+  -h | --help | help | "")
+    usage
+    ;;
+  *)
+    fail "unknown command: $command"
+    ;;
+esac

bin/omarchy-bar-text-color

@@ -0,0 +1,128 @@
+#!/bin/bash
+
+# omarchy:summary=Choose a legible transparent bar text color
+# omarchy:hidden=true
+
+set -e
+
+position=${1:-top}
+bar_size=${2:-}
+text_color=${3:-}
+background_color=${4:-}
+background_path=""
+screen_size=""
+
+shift 4 2>/dev/null || true
+while (($# > 0)); do
+  case "$1" in
+  --background)
+    background_path=${2:-}
+    shift 2
+    ;;
+  --screen)
+    screen_size=${2:-}
+    shift 2
+    ;;
+  *)
+    shift
+    ;;
+  esac
+done
+
+valid_hex() {
+  [[ $1 =~ ^#[0-9A-Fa-f]{6}$ ]]
+}
+
+fallback() {
+  printf '%s\n' "$text_color"
+  exit 0
+}
+
+contrast() {
+  local color="$1"
+  local sample="$2"
+
+  awk -v fg="$color" -v bg="$sample" '
+    function channel(hex, start) {
+      return strtonum("0x" substr(hex, start, 2)) / 255
+    }
+    function linear(c) {
+      return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ^ 2.4
+    }
+    function luminance(hex, r, g, b) {
+      r = linear(channel(hex, 2))
+      g = linear(channel(hex, 4))
+      b = linear(channel(hex, 6))
+      return 0.2126 * r + 0.7152 * g + 0.0722 * b
+    }
+    BEGIN {
+      l1 = luminance(fg)
+      l2 = luminance(bg)
+      if (l1 < l2) {
+        t = l1
+        l1 = l2
+        l2 = t
+      }
+      printf "%.6f\n", (l1 + 0.05) / (l2 + 0.05)
+    }
+  '
+}
+
+valid_hex "$text_color" || fallback
+valid_hex "$background_color" || fallback
+[[ $position =~ ^(top|bottom|left|right)$ ]] || fallback
+[[ $bar_size =~ ^[0-9]+$ ]] || fallback
+omarchy-cmd-present magick || fallback
+
+if [[ -z $background_path ]]; then
+  background_path=$(readlink -f "$HOME/.local/state/omarchy/current/background" 2>/dev/null || true)
+fi
+[[ -f $background_path ]] || fallback
+
+if [[ -z $screen_size ]]; then
+  if omarchy-cmd-present hyprctl && omarchy-cmd-present jq; then
+    screen_size=$(hyprctl monitors -j 2>/dev/null | jq -r '.[0] | "\(.width)x\(.height)"' 2>/dev/null || true)
+  fi
+fi
+[[ $screen_size =~ ^([0-9]+)x([0-9]+)$ ]] || fallback
+
+screen_width=${BASH_REMATCH[1]}
+screen_height=${BASH_REMATCH[2]}
+((screen_width > 0 && screen_height > 0 && bar_size > 0)) || fallback
+
+case "$position" in
+top)
+  crop="${screen_width}x${bar_size}+0+0"
+  ;;
+bottom)
+  crop_y=$((screen_height - bar_size))
+  ((crop_y >= 0)) || fallback
+  crop="${screen_width}x${bar_size}+0+${crop_y}"
+  ;;
+left)
+  crop="${bar_size}x${screen_height}+0+0"
+  ;;
+right)
+  crop_x=$((screen_width - bar_size))
+  ((crop_x >= 0)) || fallback
+  crop="${bar_size}x${screen_height}+${crop_x}+0"
+  ;;
+esac
+
+# Sample the first frame only. Without the selector a video background makes
+# ImageMagick decode the whole file and emit one value per frame, and the match
+# below then fails into the fallback colour.
+pixel=$(magick "$background_path[0]" -auto-orient \
+  -resize "${screen_width}x${screen_height}^" \
+  -gravity center -extent "${screen_width}x${screen_height}" \
+  -gravity NorthWest -crop "$crop" +repage \
+  -resize '1x1!' -format '%[fx:int(255*r)],%[fx:int(255*g)],%[fx:int(255*b)]' info:- 2>/dev/null || true)
+[[ $pixel =~ ^([0-9]+),([0-9]+),([0-9]+)$ ]] || fallback
+
+sample=$(printf '#%02x%02x%02x' "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "${BASH_REMATCH[3]}")
+text_contrast=$(contrast "$text_color" "$sample")
+background_contrast=$(contrast "$background_color" "$sample")
+
+awk -v text="$text_contrast" -v background="$background_contrast" 'BEGIN { exit !(background > text) }' \
+  && printf '%s\n' "$background_color" \
+  || printf '%s\n' "$text_color"

bin/omarchy-battery-capacity

@@ -1,11 +0,0 @@
-#!/bin/bash
-
-# Returns the battery full capacity in Wh (rounded to whole number).
-# Used by omarchy-battery-status for displaying battery capacity.
-
-battery_info=$(upower -i $(upower -e | grep BAT))
-
-echo "$battery_info" | awk '/energy-full:/ {
-    printf "%d", $2
-    exit
-}'

bin/omarchy-battery-low

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# omarchy:summary=Send the low battery warning notification and run battery-low hooks.
+# omarchy:args=<percentage>
+# omarchy:hidden=true
+
+set -euo pipefail
+
+if (($# != 1)); then
+  echo "Usage: omarchy-battery-low <percentage>" >&2
+  exit 1
+fi
+
+level=$1
+
+omarchy-notification-send -g 󱐋 -u critical "$(omarchy-text "Time to recharge!")" "$(omarchy-text "Battery is down to %1%" "$level")" -i battery-caution -t 30000
+omarchy-hook battery-low "$level"