m/yino
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
yino/docs/Omarchy.md
Michael Smith eeee7ace7d 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 <noreply@anthropic.com>
2026-02-15 22:35:11 +01:00

769 lines
37 KiB
Markdown
Raw Blame History

# 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/<theme-name>/`. 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 <name>` or via the Style menu
- **Install extra theme:** `omarchy-theme-install <git-url>`
- **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 <channel>` 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
Reference in New Issue View Git Blame Copy Permalink