From eeee7ace7db1bf6596802041ebf4d6e1571a685a Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Sun, 15 Feb 2026 22:35:11 +0100 Subject: [PATCH] Add comprehensive Omarchy analysis document Reference document covering the upstream Omarchy project architecture, installation process, package management, desktop stack, theming system, boot management, ISO generation, omacom-io ecosystem, and Arch-to-Debian mapping table for planning the Yino port. Co-Authored-By: Claude Opus 4.6 --- docs/Omarchy.md | 768 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 768 insertions(+) create mode 100644 docs/Omarchy.md diff --git a/docs/Omarchy.md b/docs/Omarchy.md new file mode 100644 index 0000000..ae3bbd0 --- /dev/null +++ b/docs/Omarchy.md @@ -0,0 +1,768 @@ +# Omarchy Analysis + +A comprehensive reference document analyzing the upstream Omarchy project and its ecosystem, serving as a +blueprint for the Yino (Debian-based) port. + +## 1. Project Overview + +Omarchy ("Beautiful, Modern & Opinionated Linux") is an omakase Linux distribution created by David Heinemeier +Hansson (DHH), the creator of Ruby on Rails and co-founder of 37signals/Basecamp. The name derives from +"omakase" -- a Japanese dining concept where a master chef prepares a curated selection rather than the diner +choosing from a menu. + +- **Repository:** [github.com/basecamp/omarchy](https://github.com/basecamp/omarchy) +- **Website:** [omarchy.org](https://omarchy.org) +- **Manual:** [learn.omacom.io](https://learn.omacom.io/2/the-omarchy-manual) +- **License:** MIT +- **Stars:** ~20,100 | **Forks:** ~2,000 | **Contributors:** 333 +- **Latest Release:** v3.3.3 (2026-01-08) | **Total Releases:** 48 | **Commits:** 3,214 +- **Default Branch:** `dev` +- **Language:** Shell (91.8%), CSS (3.1%), Go Template (3.1%), Lua (1.8%) +- **Sponsor:** Cloudflare (provides CDN for ISO and package delivery) + +DHH first built Omakub (an Ubuntu-based configuration) when he initially switched to Linux. After running it as +his daily driver for over a year, he evolved to a more advanced Arch-based setup and published Omarchy on June +26, 2025 as "a love letter to Linux." 37signals subsequently announced going all-in on Omarchy, planning to +switch everyone on their Ops and Ruby programming teams to it over three years. By October 2025, a petabyte of +ISOs had been delivered in a single month (~150,000 installs). + +Omarchy turns a fresh Arch Linux installation into a fully-configured, keyboard-driven desktop development system +based on Hyprland. It ships with Neovim, Ghostty, Spotify, Chromium, Typora, LibreOffice, and more. + +Key characteristics: +- Mandatory full-disk LUKS encryption +- UFW firewall enabled by default +- Wayland-only (no X11) +- Single-user auto-login (disk decryption authenticates the user) +- Btrfs filesystem with Snapper snapshots +- 14 built-in themes with atomic switching +- Super key as the primary modifier + +## 2. Repository Structure + +``` +basecamp/omarchy/ +├── .github/ISSUE_TEMPLATE/ +├── applications/ # Desktop entries, icons for TUIs and web apps +│ └── icons/ +├── bin/ # ~100+ executable scripts (omarchy-* commands) +├── config/ # Default config files for all components +│ ├── hypr/ # Hyprland, Hypridle, Hyprlock, Hyprsunset +│ ├── walker/ # Application launcher config +│ ├── waybar/ # Top bar config and indicators +│ ├── mako/ # Notification daemon +│ ├── swayosd/ # OSD overlay +│ ├── btop/ # System monitor +│ └── alacritty/ # Terminal emulator +├── default/ # Default/fallback configs and assets +│ ├── plymouth/ # Boot splash theme (script, images) +│ ├── hypr/ # Default Hyprland settings +│ ├── walker/ # Default Walker settings +│ └── waybar/ # Default Waybar settings and indicators +├── install/ # Installation system (5 phases) +│ ├── helpers/ # Shared functions (logging, guards, UI) +│ ├── preflight/ # Phase 1: Pre-install checks +│ ├── packaging/ # Phase 2: Package installation +│ ├── config/ # Phase 3: System configuration +│ │ └── hardware/ # Hardware-specific fixes +│ ├── login/ # Phase 4: Login/boot setup +│ └── post-install/ # Phase 5: Cleanup and reboot +├── migrations/ # Timestamped migration scripts +├── themes/ # Built-in theme configurations +├── .editorconfig +├── LICENSE +├── README.md +├── boot.sh # Boot-time initialization script +├── icon.png / icon.txt # Branding assets +├── install.sh # Main install entry point +├── logo.svg / logo.txt # Branding assets +└── version # Current version string +``` + +## 3. Installation Process + +The installation is orchestrated by `install.sh` which sources five phases sequentially: + +```bash +export OMARCHY_PATH="$HOME/.local/share/omarchy" +export OMARCHY_INSTALL="$OMARCHY_PATH/install" + +source "$OMARCHY_INSTALL/helpers/all.sh" +source "$OMARCHY_INSTALL/preflight/all.sh" +source "$OMARCHY_INSTALL/packaging/all.sh" +source "$OMARCHY_INSTALL/config/all.sh" +source "$OMARCHY_INSTALL/login/all.sh" +source "$OMARCHY_INSTALL/post-install/all.sh" +``` + +### Phase 1: Preflight (`install/preflight/`) + +| Script | Purpose | +| :---------------------- | :----------------------------------------------- | +| `guard.sh` | Prevent re-running on already installed systems | +| `begin.sh` | UI initialization, logo display | +| `show-env.sh` | Log environment variables | +| `pacman.sh` | Configure pacman repos and mirrors | +| `migrations.sh` | Initialize migration tracking | +| `first-run-mode.sh` | Set first-run flag | +| `disable-mkinitcpio.sh` | Defer mkinitcpio rebuilds during install | + +### Phase 2: Packaging (`install/packaging/`) + +Installs packages in categories: + +| Script | Purpose | +| :----------- | :--------------------------------------------------------- | +| `base.sh` | Core packages from `omarchy-base.packages` (~150 packages) | +| `fonts.sh` | Omarchy custom font for Waybar | +| `icons.sh` | Application icons | +| `tuis.sh` | TUI application desktop entries | + +The base package list (`install/omarchy-base.packages`) includes: + +- **Desktop:** hyprland, waybar, swaybg, mako, hypridle, hyprlock, hyprsunset, sddm, uwsm +- **Terminal:** alacritty, ghostty +- **Editor:** neovim (via custom omarchy-nvim package) +- **Browser:** chromium (custom omarchy-chromium build) +- **Apps:** spotify, typora, obsidian, signal-desktop, libreoffice-fresh, nautilus, evince, mpv +- **Dev tools:** docker, docker-compose, lazygit, lazydocker, github-cli, mise, rust, ruby +- **Utilities:** btop, fastfetch, ripgrep, fzf, bat, eza, zoxide, dust, jq, gum +- **System:** pipewire, wireplumber, power-profiles-daemon, cups, avahi, iwd, ufw +- **Fonts:** noto-fonts family, ttf-jetbrains-mono-nerd, ttf-cascadia-mono-nerd, fcitx5 +- **AUR helper:** yay + +### Phase 3: Configuration (`install/config/`) + +| Script | Purpose | +| :------------------------------- | :-------------------------------------------- | +| `config.sh` | Deploy dotfiles (3-layer system) | +| `theme.sh` | Set default theme | +| `branding.sh` | Screensaver and about text | +| `git.sh` | Set git user.name/email from install inputs | +| `gpg.sh` | GPG agent configuration | +| `timezones.sh` | Timezone setup | +| `increase-sudo-tries.sh` | More sudo password attempts | +| `increase-lockout-limit.sh` | Higher lockout threshold | +| `ssh-flakiness.sh` | SSH connection stability tweaks | +| `detect-keyboard-layout.sh` | Auto-detect keyboard layout | +| `xcompose.sh` | XCompose for special characters | +| `mise-work.sh` | mise (dev tool version manager) setup | +| `docker.sh` | Docker service and user group | +| `mimetypes.sh` | File type associations | +| `localdb.sh` | Local database config | +| `walker-elephant.sh` | Walker launcher configuration | +| `fast-shutdown.sh` | Faster shutdown timeouts | +| `sudoless-asdcontrol.sh` | Passwordless ASD control | +| `input-group.sh` | Input device permissions | +| `omarchy-ai-skill.sh` | AI tool integration | +| `powerprofilesctl-rules.sh` | Power profile udev rules | +| `wifi-powersave-rules.sh` | Wi-Fi power saving rules | +| `hibernation.sh` | Hibernation support | +| `fix-powerprofilesctl-shebang.sh`| Shebang fix for power profiles | + +Hardware-specific fixes in `config/hardware/`: + +| Script | Purpose | +| :----------------------------- | :-------------------------------------------- | +| `network.sh` | Network manager config | +| `set-wireless-regdom.sh` | Wireless regulatory domain | +| `fix-fkeys.sh` | Function key behavior | +| `bluetooth.sh` | Bluetooth service setup | +| `printer.sh` | CUPS printing | +| `usb-autosuspend.sh` | USB power management | +| `ignore-power-button.sh` | Prevent accidental shutdowns | +| `legacy-gpu-terminal.sh` | Older GPU terminal support | +| `nvidia.sh` | NVIDIA driver configuration | +| `fix-f13-amd-audio-input.sh` | Framework 13 AMD audio fix | +| `fix-bcm43xx.sh` | Broadcom Wi-Fi fix | +| `fix-apple-spi-keyboard.sh` | Apple SPI keyboard | +| `fix-apple-suspend-nvme.sh` | Apple NVMe suspend fix | +| `fix-apple-t2.sh` | Apple T2 chip support | +| `fix-surface-keyboard.sh` | Surface keyboard fix | +| `fix-asus-rog-audio-mixer.sh` | ASUS ROG audio fix | +| `fix-asus-rog-mic.sh` | ASUS ROG microphone fix | +| `fix-yt6801-ethernet-adapter.sh`| YT6801 ethernet driver | +| `fix-synaptic-touchpad.sh` | Synaptics touchpad fix | + +### Phase 4: Login (`install/login/`) + +| Script | Purpose | +| :------------------ | :--------------------------------------------------- | +| `plymouth.sh` | Install Omarchy Plymouth boot splash theme | +| `default-keyring.sh`| GNOME keyring auto-unlock setup | +| `sddm.sh` | SDDM display manager with auto-login | +| `limine-snapper.sh` | Limine bootloader + Snapper snapshot integration | + +SDDM is configured for automatic login: + +```ini +[Autologin] +User=$USER +Session=hyprland-uwsm + +[Theme] +Current=breeze +``` + +### Phase 5: Post-Install (`install/post-install/`) + +| Script | Purpose | +| :--------------- | :------------------------------------------------- | +| `pacman.sh` | Final pacman cache cleanup and config | +| `allow-reboot.sh`| Remove installer sudoers override | +| `finished.sh` | Display completion screen, prompt for reboot | + +## 4. Package Management + +Omarchy uses a three-tier package system: + +### 4.1 Pacman (Official Arch Repos) + +The standard Arch package manager. Omarchy's `pacman.conf` adds the custom Omarchy repo: + +```ini +[core] +Include = /etc/pacman.d/mirrorlist + +[extra] +Include = /etc/pacman.d/mirrorlist + +[multilib] +Include = /etc/pacman.d/mirrorlist + +[omarchy] +SigLevel = Optional TrustAll +Server = https://pkgs.omarchy.org/stable/$arch +``` + +### 4.2 OPR (Omarchy Package Repository) + +Custom packages built and hosted by the Omarchy team via the `omarchy-pkgs` repo. These include: + +- `omarchy-nvim` -- Bundled Neovim configuration +- `omarchy-walker` -- Pre-configured Walker launcher +- `omarchy-chromium` -- Custom Chromium with live theme switching +- `omarchy-zsh` / `omarchy-fish` -- Shell configurations + +The package build system (`omarchy-pkgs`) uses three tiers: + +| Tier | Build Frequency | Deployment | Review | +| :------- | :----------------- | :------------------ | :--------- | +| Stable | Manual | Stable repo only | Manual | +| Edge | Daily (6:00 AM UTC)| Edge repo only | PR review | +| Shared | Every 6 hours | Both repos | Auto-merge | + +Multi-architecture: x86_64 (native) and aarch64 (QEMU-emulated). + +### 4.3 AUR (Arch User Repository) + +Community packages installed via `yay`. The `omarchy-pkg-aur-add` script wraps yay: + +```bash +if omarchy-pkg-missing "$@"; then + yay -S --noconfirm --needed "$@" || exit 1 +fi +``` + +### 4.4 Omarchy Mirror + +A dedicated mirror of Arch core/extra/multilib repos hosted on Cloudflare R2: + +- **Stable:** `https://stable-mirror.omarchy.org/` -- runs ~1 month behind latest +- **Edge:** `https://mirror.omarchy.org/` -- tracks latest Arch repos hourly + +## 5. Desktop Environment Stack + +### 5.1 Compositor: Hyprland + +Hyprland is the Wayland compositor and tiling window manager. It's launched via UWSM (Universal Wayland +Session Manager) through SDDM. Key configuration files: + +- `~/.config/hypr/hyprland.conf` -- Main config (sources others) +- `~/.config/hypr/bindings.conf` -- User key bindings +- `~/.config/hypr/monitors.conf` -- Monitor layout +- `~/.config/hypr/input.conf` -- Input device settings +- `~/.config/hypr/looknfeel.conf` -- Theme visual settings + +Key bindings (Super = primary modifier): + +| Binding | Action | +| :--------------------- | :------------------------ | +| `Super + Return` | Terminal | +| `Super + Space` | Application launcher | +| `Super + Alt + Space` | Omarchy menu | +| `Super + W` | Close window | +| `Super + F` | Fullscreen | +| `Super + Arrow` | Navigate windows | +| `Super + Shift + B` | Browser | +| `Super + Shift + N` | Editor (Neovim) | +| `Super + Shift + F` | File manager (Nautilus) | +| `Super + Shift + M` | Music (Spotify) | +| `Super + K` | Show all keybindings | +| `Super + Ctrl + E` | Emoji picker | + +### 5.2 Top Bar: Waybar + +Waybar provides the status bar at the top of the screen. Configured in `config/waybar/config.jsonc`: + +``` +modules-left: [custom/omarchy, hyprland/workspaces] +modules-center: [clock, custom/update, custom/voxtype, custom/screenrecording-indicator] +modules-right: [group/tray-expander, bluetooth, network, pulseaudio, cpu, battery] +``` + +The Omarchy logo button in the top-left opens the Omarchy menu. + +### 5.3 Application Launcher: Walker + +Walker is the application launcher, opened with `Super + Space`. It provides fuzzy search across +applications, files, and commands. + +### 5.4 Notifications: Mako + +Mako handles desktop notifications with theme-aware styling. + +### 5.5 OSD: SwayOSD + +SwayOSD provides on-screen display for volume, brightness, and caps lock changes. + +### 5.6 Terminal: Ghostty / Alacritty + +Ghostty is the default terminal. Alacritty is also pre-installed. Users can install Kitty as well. + +### 5.7 Editor: Neovim + +Custom `omarchy-nvim` package with a pre-configured setup including LSP, Treesitter, and the +pixel.nvim colorscheme (adapts to terminal ANSI colors). + +### 5.8 Lock Screen: Hyprlock + +Hyprlock provides the lock screen with theme-aware styling and optional blurred background. + +### 5.9 Idle Management: Hypridle + +Hypridle manages screen dimming, locking, and suspend after configurable idle timeouts. + +### 5.10 Night Light: Hyprsunset + +Hyprsunset provides blue light filtering (night mode). + +### 5.11 Omarchy Menu + +A comprehensive shell script (`bin/omarchy-menu`) providing a hierarchical menu system via Walker: + +``` +Main Menu +├── Apps (Walker launcher) +├── Learn (keybindings reference) +├── Trigger (screenshot, screenrecord, share) +├── Style (theme, font, background) +├── Setup (audio, wifi, bluetooth, power, monitors, DNS, security, config) +├── Install (packages, AUR, web apps, TUIs, dev environments, editors, AI tools, gaming) +├── Remove (packages, web apps, dev environments, preinstalls) +├── Update (Omarchy, channel, config, themes, processes, hardware, firmware, password) +├── About (fastfetch system info) +└── System (lock, screensaver, suspend, hibernate, restart, shutdown) +``` + +## 6. Configuration / Dotfiles System + +Omarchy uses a 3-layer configuration system with increasing priority: + +### Layer 1: Default (lowest priority) + +Located in `~/.local/share/omarchy/default/`. These are the factory defaults shipped with Omarchy. +Users should never edit these directly. They are overwritten on every update. + +### Layer 2: Theme + +Located in `~/.local/share/omarchy/themes//`. When a theme is activated, its config files +override the defaults. Theme files cover: Hyprland, Hyprlock, Alacritty, Neovim, btop, Mako, Waybar, +Walker, SwayOSD, and backgrounds. + +### Layer 3: User (highest priority) + +Located in `~/.config/`. User edits here take ultimate precedence. Files include: + +- `~/.config/hypr/bindings.conf` -- Custom keybindings +- `~/.config/hypr/input.conf` -- Input settings +- `~/.config/hypr/monitors.conf` -- Monitor layout +- `~/.config/hypr/looknfeel.conf` -- Visual overrides +- `~/.config/omarchy/hooks/` -- User hook scripts +- `~/.config/omarchy/extensions/menu.sh` -- Menu extensions + +The `config.sh` install script deploys this layered system. The `omarchy-refresh-*` commands can +reset specific configs back to defaults. + +### Hooks + +Users can place scripts in `~/.config/omarchy/hooks/` to run at specific events. The `omarchy-hook` +script dispatches named hooks: + +```bash +HOOK_PATH="$HOME/.config/omarchy/hooks/$1" +if [[ -f $HOOK_PATH ]]; then + bash "$HOOK_PATH" "$@" +fi +``` + +## 7. Theming System + +Omarchy ships with 14 built-in themes. Each theme is a collection of config files that atomically restyle +every themed component: + +| Component | Config File | +| :------------- | :----------------------- | +| Alacritty | `alacritty.toml` | +| btop | `btop.theme` | +| Hyprland | `hyprland.conf` | +| Hyprlock | `hyprlock.conf` | +| Mako | `mako.ini` | +| Neovim | `neovim.lua` | +| SwayOSD | `swayosd.css` | +| Walker | `walker.css` | +| Waybar | `waybar.css` | +| Backgrounds | `backgrounds/` directory | + +### Theme Management + +- **Switch theme:** `omarchy-theme-set ` or via the Style menu +- **Install extra theme:** `omarchy-theme-install ` +- **Remove theme:** `omarchy-theme-remove` +- **Update themes:** `omarchy-theme-update` +- **Browse themes:** Walker menu with visual previews +- **Cycle background:** `omarchy-theme-bg-next` + +The Neovim colorscheme (`pixel.nvim`) dynamically adapts to terminal ANSI colors (0-15), meaning theme +changes in the terminal automatically propagate to the editor without any Neovim-specific theme logic. + +Custom Chromium build (`omarchy-chromium`) supports live Material Design 3 theme switching without +restarting the browser. + +### Community Themes + +Third-party themes can be installed from any Git repository. Example: +`omarchy-theme-install https://github.com/omacom-io/omarchy-synthwave84-theme.git` + +## 8. Boot Management + +### 8.1 Limine Bootloader + +Omarchy uses Limine as its bootloader (not GRUB). Limine is configured to integrate with Snapper +for bootable snapshot entries. + +### 8.2 Plymouth Boot Splash + +A custom Plymouth theme displays the Omarchy logo during boot with a progress bar animation. The +theme uses a Tokyo Night color scheme (dark background: `rgb(26, 27, 38)`). + +During boot: +1. LUKS encryption password prompt appears over the Omarchy logo +2. After password entry, a progress bar animates (fake progress with easing curve to 70%, then real + boot progress takes over) +3. On completion, SDDM auto-logs into Hyprland + +### 8.3 Snapper Snapshots + +Btrfs snapshots are managed by Snapper with these limits: + +- Maximum 30% of filesystem space for snapshots (`SPACE_LIMIT=0.3`) +- Minimum 30% free space maintained (`FREE_LIMIT=0.3`) +- Maximum 5 snapshots retained (`NUMBER_LIMIT=5`) + +Snapshots are created automatically on every `omarchy-update`. Users can also create manual snapshots +with `omarchy-snapshot create`. + +To restore: select a snapshot from the Limine boot menu, choosing by date and version. + +## 9. Security + +| Feature | Implementation | +| :-------------------- | :--------------------------------------------------- | +| Disk encryption | LUKS (mandatory during install) | +| Firewall | UFW (enabled by default) | +| GPG | GPG agent configured for signing | +| Keyring | GNOME keyring auto-unlocked on login | +| SSH | Connection stability tweaks | +| Fingerprint | Optional fprintd setup via `omarchy-setup-fingerprint` | +| FIDO2 | Optional FIDO2 key setup via `omarchy-setup-fido2` | +| Sudo | Increased retry limits, configurable lockout | +| No Secure Boot | Explicitly not supported (Microsoft ecosystem) | + +## 10. Migration System + +Omarchy uses timestamped migration scripts in the `migrations/` directory. Each migration is a shell +script named with a Unix timestamp (e.g., `1757861484.sh`). Migrations run automatically during +`omarchy-update` via `install/preflight/migrations.sh`. + +Example migration: + +```bash +echo "Add a blurred background to the lock screen" +omarchy-refresh-hyprlock +``` + +Migrations are tracked so they only run once per system. This allows Omarchy to evolve its configuration +over time without users needing to manually apply changes. + +## 11. Update System + +### Update Channels + +Four update channels with different stability levels: + +| Channel | Description | +| :------ | :---------------------------------- | +| Stable | Default. Mirrors ~1 month behind | +| RC | Release candidates | +| Edge | Latest packages, daily builds | +| Dev | Development branch | + +Switch channels via `omarchy-channel-set ` or the Omarchy menu. + +### Update Process (`omarchy-update`) + +1. Create a Btrfs snapshot (if Snapper is available) +2. Pull latest Omarchy from git +3. Run pending migrations +4. Execute the install pipeline (re-runs all phases idempotently) +5. Display update notification in Waybar + +Waybar checks for updates every 6 hours and shows a notification icon. + +## 12. ISO Generation + +The ISO is built using the `omarchy-iso` repo (`omacom-io/omarchy-iso`). + +### Architecture + +``` +omacom-io/omarchy-iso/ +├── archiso/ # Git submodule: gitlab.archlinux.org/archlinux/archiso.git +├── bin/ # Build and release scripts +│ ├── omarchy-iso-make # Build the ISO +│ ├── omarchy-iso-boot # Test via QEMU VM +│ ├── omarchy-iso-sign # GPG sign the ISO +│ ├── omarchy-iso-upload # Upload to Cloudflare R2 +│ └── omarchy-iso-release # Full build→sign→upload pipeline +├── builder/ # Build helpers and configs +└── configs/ # archiso profile configuration + ├── airootfs/ # Files overlaid onto the live system + │ ├── etc/ # System configs (mkinitcpio, Plymouth, pacman) + │ └── root/ # Automated install script + ├── efiboot/ # EFI boot loader entries + ├── grub/ # GRUB config (for ISO boot) + └── syslinux/ # Syslinux config (legacy BIOS) +``` + +### ISO Build Process + +1. The `archiso` submodule provides the ISO creation framework +2. `omarchy-iso-make` wraps archiso's `mkarchiso` command +3. The profile in `configs/` defines what goes into the ISO: + - Base packages from `omarchy-other.packages` (base, base-devel, drivers, audio stack) + - Omarchy repo packages from `omarchy-base.packages` + - Plymouth with Omarchy theme + - Automated installer script +4. The ISO includes offline package mirrors (no internet needed during install) + +### Automated Install Script + +`configs/airootfs/root/.automated_script.sh` runs on first boot from the ISO (on `/dev/tty1`): + +1. `use_omarchy_helpers()` -- Set up environment and source helpers +2. `run_configurator()` -- Launch the Omarchy Configurator (user credentials, disk selection) +3. `install_arch()` -- Run `archinstall` with the configured settings (base system, partitioning, + LUKS encryption, Btrfs, user creation) +4. `install_omarchy()` -- Chroot into the new system and run `install.sh` +5. Reboot into the installed system + +### Configurable Build + +The ISO build supports: +- `OMARCHY_INSTALLER_REPO` -- default: `basecamp/omarchy` +- `OMARCHY_INSTALLER_REF` -- default: `master` +- `--local-source` -- build from local repo copy +- `--dev` -- build development ISO + +### Distribution + +ISOs are GPG-signed and uploaded to Cloudflare R2 via rclone. The `omarchy-iso-release` script +runs the full pipeline: build → sign → upload. + +## 13. omacom-io Ecosystem + +The [omacom-io](https://github.com/omacom-io) GitHub organization maintains 20 repositories. + +### Core Infrastructure + +| Repository | Stars | Description | +| :------------------ | ----: | :------------------------------------------------------- | +| `omarchy-iso` | 176 | ISO builder wrapping archiso | +| `omarchy-pkgs` | 13 | Package build system (PKGBUILDs, signing, sync) | +| `omarchy-mirror` | 3 | Arch repo mirror on Cloudflare R2 (stable + edge) | +| `omarchy-chromium` | 26 | Custom Chromium with live theme switching (0BSD license) | + +### Shell & Editor + +| Repository | Stars | Description | +| :------------------ | ----: | :------------------------------------------------------- | +| `omarchy-zsh` | 43 | Zsh config with fzf, starship, eza, zoxide | +| `omarchy-fish` | 33 | Fish config with fzf.fish, starship, eza, zoxide | +| `pixel.nvim` | 2 | Terminal ANSI color-adaptive Neovim colorscheme (fork) | + +### Themes + +| Repository | Stars | Description | +| :---------------------------- | ----: | :--------------------------------------- | +| `omarchy-synthwave84-theme` | 26 | Example community-style theme | + +### Sibling Products + +| Repository | Stars | Description | +| :------------ | ----: | :--------------------------------------------------------- | +| `omaterm` | 26 | Headless/terminal-only Arch setup (no GUI) | +| `omamac` | 17 | macOS setup mimicking Omarchy workflow | +| `omadots` | 10 | Shared dotfiles across Omarchy, Omaterm, Omamac | + +### Websites + +| Repository | Stars | URL | +| :-------------- | ----: | :--------------------- | +| `omarchy-site` | 10 | omarchy.org | +| `omaterm-site` | 8 | omaterm.org | +| `omamac-site` | 3 | omamac.org | +| `website` | 2 | omacom.io | +| `omacon` | 18 | Conference landing page | + +### Archived + +| Repository | Note | +| :---------------------- | :------------------------------------------ | +| `omarchy-configurator` | Rolled into omarchy-iso | +| `omarchy-lazyvim` | Superseded by omarchy-nvim | +| `asdcontrol-git` | ASD control package build | + +### Notable Community Projects + +| Repository | Stars | Description | +| :------------------------------- | ----: | :--------------------------------------- | +| `goodroot/hyprwhspr` | 809 | Native speech-to-text for Linux | +| `henrysipp/omarchy-nix` | 657 | Omarchy ported to NixOS | +| `malik-na/omarchy-mac` | 530 | Omarchy for Apple Silicon Macs | +| `devmobasa/wayscriber` | 430 | Live annotation overlay for Wayland | +| `erans/hyprmon` | 385 | TUI monitor config for Hyprland | +| `bjarneo/aether` | 346 | Easy Omarchy theme creator | +| `aorumbayev/awesome-omarchy` | 259 | Curated list of Omarchy resources | +| `elpritchos/omadora` | 70 | Minimal Fedora + Hyprland (Omarchy-like) | + +## 14. Arch to Debian Mapping + +This section maps Omarchy's Arch-specific components to their Debian equivalents for the Yino port. + +### Package Management + +| Arch (Omarchy) | Debian (Yino) | Notes | +| :-------------------------------- | :----------------------------------- | :--------------------------------- | +| `pacman` | `apt` | Core package manager | +| `pacman.conf` + repos | `sources.list` + repos | Repository configuration | +| `yay` (AUR helper) | N/A or build from source | No AUR equivalent; use custom .deb repo, PPAs, or Flatpak | +| OPR (`pkgs.omarchy.org`) | Custom APT repo | Need to build .deb packages | +| `omarchy-pkgs` (PKGBUILD system) | .deb packaging (dpkg-buildpackage) | Build system needs rewrite | +| `omarchy-mirror` (Arch mirror) | Debian mirror / snapshot.debian.org | Debian is already stable | +| `pacman -S --needed` | `apt install` | Idempotent install | +| `pacman -Q` | `dpkg -l` / `apt list --installed` | Query installed packages | + +### Boot & Init + +| Arch (Omarchy) | Debian (Yino) | Notes | +| :------------------------ | :-------------------------------- | :--------------------------------- | +| `archinstall` | `debian-installer` / `preseed` | Automated installation | +| `archiso` (ISO framework) | `live-build` or `simple-cdd` | ISO generation | +| `mkinitcpio` | `initramfs-tools` or `dracut` | Initramfs generation | +| Limine bootloader | GRUB2 or systemd-boot | Consider: Limine works on Debian too | +| `mkinitcpio.conf` hooks | `initramfs-tools` hooks/scripts | Different hook system | +| Plymouth | Plymouth | Same -- available in Debian | +| Snapper | Snapper | Same -- available in Debian | +| SDDM | SDDM | Same -- available in Debian | + +### Desktop Environment + +| Arch (Omarchy) | Debian (Yino) | Notes | +| :-------------------- | :---------------------------- | :----------------------------------------- | +| Hyprland | Hyprland | Not in Debian stable; needs backport/build | +| Waybar | Waybar | Available in Debian, may need newer version | +| Walker | Walker | Needs manual build/packaging | +| Mako | Mako | Available in Debian | +| SwayOSD | SwayOSD | Needs manual build/packaging | +| Hypridle | Hypridle | Needs manual build/packaging | +| Hyprlock | Hyprlock | Needs manual build/packaging | +| Hyprsunset | Hyprsunset | Needs manual build/packaging | +| UWSM | UWSM | Needs manual build/packaging | + +### Applications + +| Arch (Omarchy) | Debian (Yino) | Notes | +| :----------------------- | :-------------------------- | :----------------------------------------- | +| Ghostty | Ghostty | Needs manual build/packaging | +| Alacritty | Alacritty | Available in Debian | +| Neovim | Neovim | Available; may need newer version | +| Chromium | Chromium | Available; omarchy-chromium needs rebuild | +| Nautilus | Nautilus | Available in Debian | +| Spotify | Spotify | Snap/Flatpak or official .deb | +| 1Password | 1Password | Official .deb available | +| Docker | Docker | Official .deb repo available | +| mise | mise | Install script or manual build | + +### System Utilities + +| Arch (Omarchy) | Debian (Yino) | Notes | +| :--------------- | :----------------- | :----------------------------------------------- | +| `gum` | `gum` | Needs manual install (Go binary) | +| `tte` | `tte` | Needs manual install (`tte-go` in omacom-io) | +| `fzf` | `fzf` | Available in Debian | +| `bat` | `bat` | Available in Debian (may be named `batcat`) | +| `eza` | `eza` | Needs manual install or cargo | +| `zoxide` | `zoxide` | Available in newer Debian or manual install | +| `ripgrep` | `ripgrep` | Available in Debian | +| `dust` | `dust` | Needs manual install or cargo | +| `lazygit` | `lazygit` | Needs manual install (Go binary) | +| `lazydocker` | `lazydocker` | Needs manual install (Go binary) | +| `fastfetch` | `fastfetch` | Available in newer Debian or manual build | +| `btop` | `btop` | Available in Debian | +| `ufw` | `ufw` | Available in Debian | + +### Things to Remove / Simplify for Yino + +Since Debian is a stable release (not rolling), several Omarchy mechanisms become unnecessary or simpler: + +| Omarchy Feature | Yino Approach | +| :--------------------------- | :------------------------------------------------------- | +| Arch mirror with 1-month lag | Not needed -- Debian stable is already conservative | +| `disable-mkinitcpio.sh` | Not needed -- Debian uses initramfs-tools | +| Edge/Dev update channels | Simpler: just stable + backports | +| Frequent migrations | Fewer needed -- stable base changes less | +| AUR | Not applicable -- use custom .deb repo or Flatpak | +| `omarchy-pkgs` build system | Rewrite for .deb packaging if custom packages are needed | +| Apple T2 support | Optional -- evaluate if needed for target hardware | +| NVIDIA-specific fixes | Keep but adapt for Debian's nvidia packaging | + +### Key Porting Challenges + +1. **Hyprland and related tools** -- Not in Debian stable; need to either: + - Build from source and package as .deb + - Use a PPA or third-party repo + - Backport from Debian unstable/experimental + +2. **ISO generation** -- Replace `archiso` with `live-build` or `simple-cdd`; rewrite the automated + installer to use `debian-installer` with preseed or a custom script + +3. **Package repository** -- Replace PKGBUILD-based `omarchy-pkgs` with .deb packaging if custom + packages are needed + +4. **Walker** -- Not packaged for Debian; needs manual build + +5. **Ghostty** -- Not packaged for Debian; needs manual build + +6. **omarchy-chromium** -- Significant effort to rebuild custom Chromium for Debian; consider whether + the live theme switching is worth the build complexity, or use standard Chromium