omarchy-omakase

A personal overlay on Omarchy (Arch + Hyprland), applied by one idempotent script: terminal, editor, window manager config, a Quickshell bar with panels, and agent-usage helpers.

Shell · QMLpersonalBase Omarchy (Arch, Hyprland)Entry point setup.shShell Quickshell (QML)Config language Hyprland Luagithub.com/javabetatester/omarchy-omakase

Overview

omarchy-omakase is an overlay on Omarchy. It does not reinstall the window manager: it copies a personal rice into the user's config directories and never edits /usr/share/omarchy.

Everything is applied by one script, setup.sh, split into modules. Each module backs up what it overwrites, and every module can be rerun. An older script that rewrote the whole hyprland.conf and patched QML with sed was dropped in favour of this overlay model.

PieceWhat it brings
TerminalKitty, with the Omarchy theme included and Ctrl+Shift+Q unbound so it cannot close the window
EditorNeovim with LazyVim: explorer, bottom terminal, problems panel
Window managerHyprland user config in ~/.config/hypr (Lua), loaded after the Omarchy defaults
BarA Quickshell bar and panels, running next to the omarchy shell
PromptStarship

Run it

backuppkgsnvimhypr$HOMEpass 1: installpkgsnvimhyprpass 2: already there, skip
Each module is installed once and overwritten files are backed up; a second run finds everything already in place.

Prerequisite: Omarchy on Arch. Without it the overlay still copies files, but some Hyprland IPC calls need Omarchy; setup.sh warns when it is not detected.

sh
git clone https://github.com/javabetatester/archin-coding.git
cd archin-coding
chmod +x setup.sh
./setup.sh all

Without arguments setup.sh opens a menu. You can also name modules, or list them:

sh
./setup.sh              # interactive menu
./setup.sh nvim
./setup.sh kitty nvim
./setup.sh hypr
./setup.sh --list

After a run, hyprctl reload is usually enough for stale binds. Open nvim once so Lazy finishes the plugin sync.

ModuleIn allWhat it does
packagesyesnvim, kitty, thunar, ripgrep, fd, lazygit, grim, slurp, wl-clipboard, playerctl, pavucontrol, python-pywal, and more
kittyyesInstalls ~/.config/kitty/kitty.conf
nvimyesLazyVim overlay; clones the starter if no config exists; adds the neo-tree extra; headless Lazy sync
hypryesBinds, look and feel, input, window rules, KEYBINDS.md in ~/.config/hypr
scriptsyesHelper scripts in ~/.config/scripts, bar launcher in ~/.local/bin
starshipyes~/.config/starship.toml
baryesQuickshell rice in ~/.config/quickshell and account helpers in ~/.local/bin
extrasyesThunar, KDE Connect, mpd-mpris, Vesktop from the AUR when a helper exists
shellyesalias cls='clear' appended to .bashrc (and .zshrc if present)
hypr-monitorsnomonitors.lua for one specific machine; skip on other hardware

What changes

Files land under the home directory only. Before each overwrite the previous file is copied to a backup directory.

PathWritten by
~/.config/hypr/*.lua, KEYBINDS.mdhypr
~/.config/hypr/monitors.luahypr-monitors
~/.config/kitty/kitty.confkitty
~/.config/nvim/ (overlay, lazyvim.json)nvim
~/.config/quickshell/bar
~/.config/scripts/scripts
~/.local/bin/ (bar launcher, account helpers, chaves)scripts, bar
~/.config/starship.tomlstarship
~/.dotfiles-backup-archin-<timestamp>/Backups of every overwritten file

Copies never delete extra files in the destination: archin_install_tree backs up colliding files and copies over them, leaving anything else in place.

Architecture

Omarchy basehyprkittynvimstarship + scriptsbaroverlay
Omarchy is the base; each overlay module is a layer copied on top of it.

setup.sh sources lib/common.sh and every modules/*.sh. Each module registers itself with archin_register and exposes one function archin_install_<name>; the runner maps a module name to that function and calls it.

text
setup.sh
  |-- lib/common.sh   archin_pkg, archin_aur, archin_backup,
  |                   archin_install_file, archin_install_tree, archin_ensure_line
  |-- modules/*.sh    archin_register <name> <desc>; archin_install_<name>
  `-- overlay/        files copied as-is into $HOME
        hypr/  kitty/  nvim/  quickshell/  scripts/  local-bin/
        starship.toml  hypr-monitors/
  • archin_pkg runs pacman -S --needed --noconfirm; archin_aur uses yay or paru and warns when neither exists.
  • archin_install_file backs up the destination, then copies one overlay file.
  • archin_install_tree walks an overlay directory with find, backing up and copying each file.
  • archin_ensure_line appends a line to a file only when it is not already present, which makes the shell module idempotent.

Session start

How the pieces come alive on login, through the Hyprland user config.

  1. 1Omarchy defaults loadhyprland.lua bootstraps Omarchy, requires its defaults, then requires the user files: monitors, input, bindings, looknfeel, autostart.
  2. 2Autostart runsautostart.lua launches kdeconnect-indicator and mpd-mpris when present, starts the bar through start-archin-bar.sh, then runs agent-usage-refresh.sh.
  3. 3The bar starts alonestart-archin-bar.sh runs qs -n -d -p ~/.config/quickshell. It never pkills quickshell by name, because that would kill the omarchy shell.
  4. 4Binds toggle panelsBindings call the shell over IPC (for example launcher toggle, dashboard toggle, music toggle); shell.qml holds the visibility flags for each overlay.

Hyprland keys

Super is the Windows key. Super+K opens the tutorial. Source: overlay/hypr/KEYBINDS.md.

KeysAction
Super + EnterTerminal (Kitty)
Super + Shift + EnterFloating terminal
Super + DLauncher
Super + EThunar
Super + ADashboard (agents)
Super + MMusic panel
Super + XLock screen (hyprlock)
Super + Shift + KChaves: copy a password (rbw)
Super + Ctrl + Shift + KChaves: copy a 2FA code
MenuDefine (dictionary)
KeysAction
Super + Shift + Q, Super + WClose window
Super + Shift + Space, Super + Shift + VToggle floating
Super + FFullscreen
Super + P, Super + JPseudo, toggle split
Super + arrowsMove focus
Super + Shift + arrowsMove window
Super + Ctrl + arrowsResize window
Super + Tab, Super + Shift + TabNext, previous window
Super + 1 to 5Go to workspace 1-5
Super + Shift + 1 to 5Move window to workspace
Super + scrollSwitch workspace
Super + S, Super + Shift + SSpecial workspace, move to it
Super + N, Super + Shift + NOpen, close notifications
KeysAction
F1, F2, F3Mute, volume down, volume up
Print, Shift + PrintScreenshot, area screenshot
Super + R, Super + Shift + RStart, stop recording
Super + SpaceApp launcher (wofi)
Super + C, Super + VCopy, paste
Super + Ctrl + VClipboard history
Super + EscapeExit menu (wlogout)
Super + Alt + SpaceOmarchy menu

Where a key is reused, bindings.lua calls hl.unbind first and then o.bind, so the Omarchy default does not conflict. Window rules in the same folder set opacity per app class and float mpv, floatingterm and scratchterm; layer rules blur every namespace starting with archin-.

Neovim and Kitty

Leader is Space. Source: overlay/nvim/KEYBINDS.md, also copied to ~/.config/nvim/KEYBINDS.md.

KeysAction
Ctrl+EExplorer
Ctrl+'Bottom terminal, open or hide
Ctrl+Shift+'New terminal
2 then Ctrl+'Terminal 2
Ctrl+H/J/K/LSwitch split, also from inside the terminal
Space tk, Ctrl+Shift+QKill the terminal panel
Esc Esc then QKill the focused terminal
Space xxProblems (lint)
]d, [dNext, previous diagnostic
Space SpaceFind file
gd, KGo to definition, hover

Run the kitty module together with nvim. Without map ctrl+shift+q no_op in kitty.conf, Ctrl+Shift+Q closes the whole emulator instead of the terminal panel.

Bar and panels

musicagentswifivault
The Quickshell bar is a strip; each panel opens like a drawer under it.

The bar is a Quickshell config (shell.qml and components/*.qml). Its layer namespace starts with archin-, which is what the Hyprland layer rules match for blur. It polls the system with small Process blocks: cava for the visualizer, playerctl and wpctl for media and volume, nmcli for Wi-Fi, the battery capacity file, and hyprctl clients -j for open windows.

ComponentRole
Bar.qmlThe bar itself: media, volume, Wi-Fi, battery, open windows
Dashboard.qmlOverlay opened with Super+A; sections include agents and the vault
AgentsPanel.qmlAgent usage: reads the JSON records and refreshes every 15 and 30 seconds
AccountTokenUsage.qml, ClaudeAccounts.qmlPer-account usage and Claude account switching
VaultPanel.qmlSearchable Bitwarden logins and Infisical keys; secrets go from the CLI straight to the clipboard
LauncherPanel.qmlApp launcher with usage-ranked results
MusicPanel.qmlPlayback controls
WifiPanel.qml, BluetoothPanel.qmlNetwork and device panels
AudioMixerPanel.qmlDefault volume, sinks and per-app streams, fed by audio-mixer-status
DisplayPanel.qmlDisplay controls

Agent usage

The agents panel only reads JSON files from $XDG_STATE_HOME/omarchy/agents/usage (default ~/.local/state/omarchy/agents/usage). Collectors write one record per provider, so the panel never talks to a provider API itself.

ScriptSource of data
agent-usage-codexNative Codex CLI sessions, pi/omp sessions that ran through openai-codex, opencode sessions on an OpenAI provider; limits and plan from the Codex app-server RPC. Flags: --force, --limits-only
agent-usage-cursorCursor's local state.vscdb plus the Cursor dashboard plan and usage endpoints
agent-usage-grokGrok billing and user endpoints plus local sessions under ~/.grok, with a token refresh
agent-usage-refresh.shRuns omarchy-agent-usage-update --limits-only for the other providers, then writes codex.json atomically from a temp file only if jq accepts it
Helper in ~/.local/binRole
claude-accounts, codex-accountsStore and switch several accounts per CLI
agent-account-limits, agent-account-tokensLimits and token usage per stored account
desktop-vaultMetadata-only bridge between the vault panel and the bw and infisical CLIs; clears the clipboard after a timeout only if its hash is unchanged
chavesrbw picker that copies a password, user or TOTP code; the clipboard is cleared after 30 seconds

Other scripts in ~/.config/scripts: audio-mixer-status dumps volume, sinks and streams as JSON; define.sh looks the selected word up in a public dictionary API and shows a notification; Music.sh opens rmpc in Kitty, or Spotify through Omarchy, or tells you to install rmpc.

Decisions

DecisionChosenRejectedWhy
Relation to OmarchyOverlay in user config, never touching /usr/share/omarchyA full rewrite of hyprland.confOmarchy updates keep improving defaults without clobbering personal files
Re-runningIdempotent modules with backupsOne-shot installerSafe to run again after any change
Bar processSecond Quickshell instance with its own config pathpkill quickshell and replace the shellKilling quickshell by name would kill the omarchy shell
Machine-specific confighypr-monitors excluded from allMonitors in the default setDisplay layout only fits one machine
Secrets in panelsCLI to clipboard, metadata-only bridge, timed clearStoring or displaying secretsSecrets never sit in the panel state

Limits: the vault and Chaves need rbw, bitwarden-cli and infisical-bin installed by hand. The Infisical URL comes from ~/.config/quickshell/state/vault.json (infisical.apiUrl) or INFISICAL_API_URL. Package installs assume pacman; the AUR step is skipped without yay or paru. Stays manual: logging into each agent CLI and vault, editing monitors.lua for other hardware, and installing rmpc for the music script.

Key files