GNOME, Plasma, and Mac desktop metaphors — on Omarchy, on Hyprland.
Familiar is a single plugin that swaps the feel of the shell: bar, dock, launcher, overview, and window switcher. It keeps Omarchy’s theme, menu, notifications, and lock screen. It does not ship brand icons, fonts, or wallpapers.
Repo: github.com/tuxclaw/familiar
Independent software. Not affiliated with, endorsed by, or sponsored by Omarchy, GNOME, KDE, Plasma, or Apple. Those names describe interaction paradigms only.
- What it is
- Status
- Install
- Profiles
- Using it
- Hyprland Lua
- Configuration
- Architecture
- Develop
- Uninstall
- Limits
- License
One plugin id, three kinds:
| Kind | File | Role |
|---|---|---|
bar |
Bar.qml |
Full top/bottom bar replacement |
overlay |
Overlay.qml |
Dock + launcher + overview + switcher (IPC surface) |
service |
Service.qml |
Active profile, shell.json persistence |
It never declares panel — Omarchy prefers panel over overlay for summon, and that would hide the dock.
Target runtime: Omarchy 4.0.2 Quattro (omarchy-shell, one Quickshell process) on Hyprland 0.56.2 (Lua config, not Hyprlang).
| Milestone | What | State |
|---|---|---|
| M0 | Manifest, service, overlay IPC, profile JSON, Lua fragments, tests | Done |
| M1 | Profile bars + stock Omarchy widget host | Done |
| M2 | Overlay dock, pins, running apps, autohide | Done |
| M3 | Launcher (grid / kickoff / spotlight) + dock Applications tile | Done |
| M4 | Overview + switcher | Done |
| M5 | Motion polish, light theme, hot corner, Hypr writer, docs/assets | Live reapply and setProfile proven; marketplace listing pending |
Default branch: main (M0–M5). Milestone branches andy/m0-skeleton … andy/m5-polish remain as history.
omarchy plugin add https://github.com/tuxclaw/familiar.git --enable --yes
omarchy bar use io.github.tuxclaw.familiar
omarchy restart shellPlugin directory must be ~/.config/omarchy/plugins/io.github.tuxclaw.familiar — that id is the live contract, not the GitHub repo name.
Right-click Activities (GNOME) or Applications (Plasma / Mac) and pick GNOME, Plasma, or Mac. Left-click still opens overview or the launcher. Super+Shift+F cycles. IPC still works:
omarchy-shell shell call io.github.tuxclaw.familiar setProfile gnome
omarchy-shell shell call io.github.tuxclaw.familiar setProfile plasma
omarchy-shell shell call io.github.tuxclaw.familiar setProfile macos
omarchy-shell shell call io.github.tuxclaw.familiar cycleProfile ''
omarchy-shell shell call io.github.tuxclaw.familiar getProfile ''| GNOME | Plasma | Mac | |
|---|---|---|---|
| Bar | Top, 32px. Activities + pips; weather/clock/bell centered | Bottom, 40px. Applications + tasks; tray/clock flush right | Top, 28px. App menu + active app |
| Dock | Off in profile JSON; enable with bar.dockEnabled=on |
Off | On, magnify, bottom |
| Launcher | App grid (Super+A) | Kickoff list | Spotlight list |
| Overview | Activities | Present Windows | Mission Control |
| Switcher | App row | Window thumbs | App row |
GNOME’s bar has no Applications button. Open the launcher with Super+A, or from the dock Applications tile if the dock is enabled (last icon on the right; hover the bottom edge if autohide is on).
Omarchy menu stays on Super+Alt+Space in every profile.
Summon overlay surfaces (JSON string, hits Overlay.qml):
omarchy-shell shell summon io.github.tuxclaw.familiar '{"surface":"launcher"}'
omarchy-shell shell summon io.github.tuxclaw.familiar '{"surface":"overview"}'
omarchy-shell shell summon io.github.tuxclaw.familiar '{"surface":"switcher","scope":"app"}'
omarchy-shell shell summon io.github.tuxclaw.familiar '{"surface":"switcher","scope":"window"}'
omarchy-shell shell toggle io.github.tuxclaw.familiar '{"surface":"launcher"}'
omarchy-shell shell hide io.github.tuxclaw.familiarLauncher: type to filter, arrows to move, Enter to launch, Escape to close. Ranking is prefix → word-start → fuzzy, then frecency at ~/.local/state/familiar/frecency.json. Omarchy menu commands appear after two characters.
Click Activities on the GNOME bar for overview. Right-click it (or Plasma/Mac Applications) to switch desktop profiles.
Familiar never writes Hyprlang. It concatenates hypr/common.lua + hypr/<profile>.lua.
Generate (GNOME example):
./tests/hypr.sh --profile gnome --output ~/.config/hypr/familiar.luaIn ~/.config/hypr/hyprland.lua, insert immediately after require("hypr.looknfeel") — never after bindings:
require("hypr.familiar") -- familiar:requireThen:
hyprctl reload
hyprctl configerrorsDock autohide keeps the layer mapped. Compositor blur uses ignore_alpha = 0.2 so a hidden dock does not leave a blur ghost.
Service.qml applyHypr() takes no arguments and writes only the fixed live path. Profile switching regenerates familiar.lua, reloads Hyprland, checks configuration errors, and restores the previous file if validation fails.
| Key | Familiar | Replaces |
|---|---|---|
| Super tap | Overview | Super-only |
| Super+A | Launcher | — |
| Alt+Tab | App switcher | Next window |
| Super+S | Overview | Omarchy scratchpad |
| Super+Shift+F | Cycle profile | — |
| Super+Space | (unchanged) | Omarchy menu |
Plasma and Mac fragments rebind a different set (hypr/plasma.lua, hypr/macos.lua). Mac takes Super+Space for Spotlight-style launcher — unbind first.
Persisted in ~/.config/omarchy/shell.json on the bar: object (Familiar is the active bar). Extra keys survive host saves.
| Key | Values | Notes |
|---|---|---|
bar.id |
io.github.tuxclaw.familiar |
Active bar |
bar.profile |
gnome plasma macos |
|
bar.dockEnabled |
auto on off |
auto → profile default |
bar.dockAutohide |
auto on off |
Needs omarchy restart shell to remount |
bar.dockPinned |
comma-separated desktop ids | e.g. chromium,org.gnome.Nautilus,obsidian |
bar.dockPosition |
auto bottom left right |
|
bar.dockIconSize |
integer | |
bar.dockMagnification |
auto on off |
service.resolved() is not reactive. Dock enable/autohide changes need omarchy restart shell.
omarchy-shell (Quickshell)
└─ io.github.tuxclaw.familiar
├─ service profile store ──► ~/.config/hypr/familiar.lua
├─ overlay dock + open(payload) → launcher | overview | switcher
└─ bar full bar; stock widgets via barWidgetRegistry
Theme comes from qs.Commons.Color / Style (already loaded from Omarchy’s current theme). Familiar does not parse TOML.
familiar/
├── manifest.json
├── Bar.qml Overlay.qml Service.qml Familiar.qml
├── profiles/{gnome,plasma,macos}.json
├── hypr/{common,gnome,plasma,macos}.lua
├── ui/bar ui/dock ui/launcher ui/overview ui/switcher
├── lib/Apps.js
└── tests/{validate.sh,hypr.sh}
./tests/validate.sh
./tests/hypr.shqmllint is /usr/lib/qt6/bin/qmllint -I /usr/share/omarchy/shell.
Plugin QML under ~/.config/omarchy/plugins/ hot-reloads on save. New files / new QML types often need omarchy restart shell. Do not spawn a second quickshell.
Hard rules learned on this box:
- Never
requiredonomarchyPath/barWidgetRegistry/barConfig(host injects after create). - Never assign Loader
implicitHeight/implicitWidth(read-only; bar vanishes). - Host fallback bug: if Familiar fails to load,
shell.qmlerrorStringis undefined and the bar is gone. Revert:omarchy bar use omarchy.bar.
omarchy bar use omarchy.bar
omarchy-shell shell call io.github.tuxclaw.familiar uninstall ''
omarchy plugin disable io.github.tuxclaw.familiar
omarchy plugin remove io.github.tuxclaw.familiarRemove the guarded require("hypr.familiar") from hyprland.lua if you added it. Backup from this machine: ~/.config/hypr/hyprland.lua.bak.familiar.20260904153012.
- Plugins run unsandboxed. Familiar does no network and performs no privilege escalation.
preview.pngis a GNOME launcher shot from this machine (2560×1440).- Overview thumbs cap live
ScreencopyViewat 12. - Switcher commits on modifier release when detected, else 1.2s fallback.
- Drag-to-workspace in overview is not guaranteed.
- Not listed on plugins.omarchy.org yet.
MIT. See LICENSE.