swadhin / de-omarchy public

Rewrite README: accurate keybindings, safety contract, architecture docs

swadhinbiswas committed 2 months ago

d6e0add

1 parent a4134b1

commit d6e0add

1 file changed

+147 -44

Files

README.md +147 -44

Showing 1 changed file+147-44

README.md

▼README.md

+147-44

@@ -1,41 +1,63 @@
1	1	# de-omarchy
2	2
3		-Omarchy's Hyprland desktop UI for any Arch-based distro. Bar, launcher, theming, notifications, lock screen, system monitor — without touching your system layer.
	3	+The Omarchy desktop, layered onto any Arch-based system.
4	4
5		-## What it does
	5	+de-omarchy takes the [Omarchy](https://github.com/omarchy/omarchy) Hyprland experience — the Quickshell bar, launcher, theming, notifications, lock screen, screensaver — and installs it as a self-contained desktop layer on top of an existing Arch, CachyOS, EndeavourOS, or Manjaro setup. Your system stays yours: no ISO, no bootloader, no display manager, no mirrors touched. Everything de-omarchy adds is additive, marked, and reversible.
6	6
7		-- Omarchy Quickshell shell (bar, app drawer, menu, notifications, clipboard, emojis, lock screen, panels)
8		-- 22 themes with live switching (`omarchy theme set <name>`)
9		-- Hyprland look: gaps, borders, animations, window rules matching upstream defaults
10		-- System monitor bar widget (CPU, RAM, disk, GPU temp, network speed)
11		-- `omarchy` CLI (`omarchy --help`, `omarchy theme list`, etc.)
12		-- Full keybinding system with cheat sheet (`SUPER+H`)
	7	+Ported from Omarchy by DHH (MIT). See [Credits](#credits).
13	8
14		-## What it does NOT do
	9	+---
15	10
16		-- Does not touch pacman.conf, mirrors, kernels, bootloaders, or display manager
17		-- Does not replace your login shell — zsh stays, hook via `~/.config/zshrc.d/*.zsh` glob
18		-- Does not overwrite terminal config, starship prompt, or SSH keys
19		-- Does not install GNOME or Yaru packages
20		-- Adds one marked block to `hyprland.lua` — delete to revert
	11	+## Highlights
	12	+
	13	+\| \| \|
	14	+\|---\|---\|
	15	+\| Quickshell shell \| Bar, launcher, menus, notifications, clipboard, emojis, lock screen, OSD \|
	16	+\| 10 bar styles \| Classic → Floating Islands → Glass → OLED Black… cycle live with `SUPER + CTRL + Y` \|
	17	+\| 22 themes \| Live switching, `omarchy theme set "Tokyo Night"` \|
	18	+\| System monitor widget \| CPU, RAM, disk, GPU temp, network throughput — every 2 s, click for btop \|
	19	+\| Notification center \| Bell widget + history panel, `SUPER + ALT + N` \|
	20	+\| Plugin marketplace \| Browse and install community plugins from the Plugin Library (`SUPER + SHIFT + I`) \|
	21	+\| Monitor Manager \| Visual multi-monitor arrangement, `SUPER + CTRL + M` \|
	22	+\| Animated screensaver \| Terminal-text-effects engine, random effect each idle — exactly upstream \|
	23	+\| ~440 CLI commands \| The full `omarchy-*` surface, routed through one `omarchy` entry point \|
	24	+\| Agent skills \| Ships Omarchy skills symlinked into Claude Code, Codex, Gemini, and friends \|
21	25
22	26	## Requirements
23	27
24		-- Arch-based distro (CachyOS, Arch, EndeavourOS, Manjaro)
25		-- Hyprland 0.56+ with Lua config
26		-- `quickshell` (repo package)
27		-- paru or yay (AUR helper)
	28	+- An Arch-based distro already running Hyprland configured via Lua (`hyprland.lua`)
	29	+- [`quickshell`](https://quickshell.outfoxxed.me/) — repo package on Arch/CachyOS
	30	+- `paru` or `yay` for the handful of AUR-only packages (e.g. `python-terminaltexteffects`, `xdg-terminal-exec`)
	31	+- `git`, `rsync`, `curl`
28	32
29	33	## Install
30	34
31	35	```bash
32	36	git clone https://github.com/swadhinbiswas/de-omarchy.git ~/de-omarchy
33	37	cd ~/de-omarchy
34		-./scripts/diff-preview.sh # dry run
35		-./install.sh # backs up first, then applies
	38	+
	39	+./scripts/diff-preview.sh # dry run — see exactly what would change
	40	+./install.sh # targeted backup first, then apply
36	41	```
37	42
38		-After install: `hyprctl reload` or re-login.
	43	+Then `hyprctl reload` — or log out and back in so environment variables settle everywhere.
	44	+
	45	+### What the installer does, in order
	46	+
	47	+1. Backs up every file it could touch (plus `.ssh`, zsh stack, starship) to `~/.de-omarchy-backups/<timestamp>/`
	48	+2. Installs missing UI packages only — never upgrades what you have
	49	+3. Deploys the runtime to `/usr/share/de-omarchy` (`rsync -a --delete` of `bin/ shell/ themes/ default/ config/ …`)
	50	+4. Installs additive hooks: three symlinks into `~/.config/hypr/`, one into `~/.config/zshrc.d/` — all pointing at runtime copies, never at your git checkout
	51	+5. Appends one clearly-marked block to `~/.config/hypr/hyprland.lua` (pre-change copy saved next to it)
	52	+6. Initializes Omarchy state and applies the rose-pine theme
	53	+
	54	+Idempotent: safe to re-run any time.
	55	+
	56	+### The safety contract
	57	+
	58	+Never touched: `pacman.conf`, mirrors, repos, kernel, bootloader, display manager, SDDM, monitors layout, `.zshrc`, `.zshenv`, `starship.toml`, `kitty.conf`, SSH keys. Existing configs are merged `--ignore-existing`; nothing in `$HOME` is deleted or overwritten.
	59	+
	60	+Added: the runtime dir, the four symlinks above, the marked Hyprland block, `/etc/environment.d/10-de-omarchy.conf` (sets `OMARCHY_PATH`), a PAM stanza for the lock screen, and symlinks for a dozen key commands into `/usr/bin`.
39	61
40	62	## Uninstall
41	63
@@ -43,42 +65,123 @@ After install: `hyprctl reload` or re-login.
43	65	./uninstall.sh
44	66	```
45	67
46		-Restores everything from `~/.de-omarchy-backups/<timestamp>/`.
	68	+Strips the marked block, removes the symlinks, deletes the runtime — then restore anything else from `~/.de-omarchy-backups/<timestamp>/`. Your desktop returns to its pre-install state after `hyprctl reload`.
47	69
48	70	## Keybindings
49	71
	72	+Your existing bindings win — de-omarchy only claims keys that are free. The essentials:
	73	+
50	74	\| Key \| Action \|
51	75	\|---\|---\|
52		-\| `SUPER+M` / `SUPER+D` / `SUPER tap` \| App drawer \|
53		-\| `SUPER+H` \| Keybinding cheat sheet \|
54		-\| `SUPER+T` \| Theme switcher \|
55		-\| `SUPER+SHIFT+M` \| Omarchy menu \|
56		-\| `SUPER+W` \| Background switcher \|
57		-\| `SUPER+E` \| Yazi file manager \|
58		-\| `SUPER+RETURN` \| Terminal (kitty) \|
59		-\| `SUPER+L` \| Lock screen \|
	76	+\| <kbd>SUPER</kbd> + <kbd>SHIFT</kbd> + <kbd>M</kbd> \| Omarchy menu \|
	77	+\| <kbd>SUPER</kbd> + <kbd>K</kbd> \| Keybindings cheat sheet window \|
	78	+\| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>Y</kbd> \| Cycle bar style \|
	79	+\| <kbd>SUPER</kbd> + <kbd>ALT</kbd> + <kbd>N</kbd> \| Notification center \|
	80	+\| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>M</kbd> \| Monitor Manager \|
	81	+\| <kbd>SUPER</kbd> + <kbd>SHIFT</kbd> + <kbd>I</kbd> \| Plugin Library \|
	82	+\| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>A</kbd> / <kbd>B</kbd> / <kbd>W</kbd> \| Audio / Bluetooth / Network panel \|
	83	+\| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>SPACE</kbd> \| Background switcher \|
	84	+\| <kbd>SUPER</kbd> + <kbd>PRINT</kbd> / <kbd>ALT</kbd> + <kbd>PRINT</kbd> \| Screenshot / screen recording \|
	85	+\| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>T</kbd> \| Activity (btop) \|
	86	+\| <kbd>SUPER</kbd> + <kbd>grave</kbd> \| Scratchpad \|
	87	+
	88	+Full map, including preserved host bindings and documented conflict decisions: [`keybindings/KEYMAP.md`](keybindings/KEYMAP.md).
	89	+
	90	+## The CLI
	91	+
	92	+One router, ~440 self-documenting commands:
	93	+
	94	+```console
	95	+$ omarchy --help # grouped, searchable command index
	96	+$ omarchy theme list # 22 themes
	97	+$ omarchy theme set catppuccin # live switch
	98	+$ omarchy bar style list # the 10 bar presets
	99	+$ omarchy bar style set glass # repaint the bar
	100	+$ omarchy plugins marketplace # browse the community catalog
	101	+$ omarchy plugin add <git-url> # sideload a plugin
	102	+$ omarchy shell toggle omarchy.audio # IPC into the running shell
	103	+```
	104	+
	105	+Every command carries machine-readable metadata (`# omarchy:summary=…`), so `--help`, menus, and AI agents all read the same source of truth.
	106	+
	107	+## Shell plugins
	108	+
	109	+Plugins are Quickshell components with a `manifest.json`: kinds are `bar-widget`, `panel`, or `service`. First-party plugins ship under `/usr/share/de-omarchy/shell/plugins/` and load automatically; user-installed ones live in `~/.config/omarchy/plugins/` and merge in at scan time (first-party ids — anything under the reserved `omarchy.*` namespace — always win).
	110	+
	111	+Open Plugin Library (`SUPER + SHIFT + I`) to browse the bundled catalog plus the [omarchyplugins.com](https://omarchyplugins.com) marketplace, or drive it headless:
	112	+
	113	+```console
	114	+$ omarchy plugins list
	115	+$ omarchy plugins install docker-status
	116	+$ omarchy-shell shell setPluginEnabled deomarchy.power-profile true
	117	+```
60	118
61		-Existing keybindings preserved. Full map: `keybindings/KEYMAP.md`.
	119	+## Themes
	120	+
	121	+22 themes, each a single `themes/<name>/colors.toml`. Templates under `default/themed/*.tpl` consume `{{ variable }}` placeholders and render into your terminal, GTK, and shell configs at switch time. Making a theme is making one TOML file:
	122	+
	123	+```bash
	124	+cp -r themes/rose-pine themes/my-theme && $EDITOR themes/my-theme/colors.toml
	125	+omarchy theme set my-theme
	126	+```
	127	+
	128	+## Screensaver
	129	+
	130	+The real Omarchy screensaver: your branding art rendered by [terminal-text-effects](https://github.com/ChrisBuilds/terminaltexteffects) at 120 fps, a random effect every idle, cursor hidden, exits on any input. Provided by `python-terminaltexteffects` (AUR) — installed automatically; without it the screensaver degrades gracefully to static art rather than failing.
62	131
63	132	## Architecture
64	133
	134	+```
	135	+~/de-omarchy (source, yours) /usr/share/de-omarchy your session
	136	+┌──────────────────────────┐ rsync ┌──────────────────────┐ symlinks ┌─────────────────┐
	137	+│ bin/ shell/ themes/│ ───────▶ │ OMARCHY_PATH (root) │ ──────────▶ │ ~/.config/hypr/ │
	138	+│ default/ config/ docs/ │ │ │ │ ~/.config/zshrc.d/
	139	+└──────────────────────────┘ └──────────────────────┘ └─────────────────┘
	140	+ edit here the desktop runs HERE override slot
	141	+```
	142	+
	143	+Three layers, one direction of truth:
	144	+
	145	+- Source repo — where you edit. Never referenced at runtime.
	146	+- Runtime (`OMARCHY_PATH`, set via `/etc/environment.d`) — the authoritative copy every process reads: Hyprland Lua modules, the Quickshell shell, all `omarchy-*` commands, plugin manifests.
	147	+- Live config — `~/.config/hypr/deo-.lua` are override slots*: plain symlinks you may replace with your own files. Hyprland's Lua loader resolves modules in order `~/.local/state/` → `~/.config/` → `$OMARCHY_PATH/`, so user state beats fork defaults beats nothing.
	148	+
	149	+Because the runtime is authoritative, deleting or breaking the source checkout cannot hurt a running desktop.
	150	+
	151	+### Deploy loop for development
	152	+
	153	+\| You changed \| Deploy \| Apply \|
	154	+\|---\|---\|---\|
	155	+\| a `bin/omarchy-*` script \| `sudo cp bin/omarchy-x /usr/share/de-omarchy/bin/` \| nothing needed \|
	156	+\| Hyprland Lua (`default/hypr/`, `config/hypr/`) \| same pattern into `runtime/<same path>` \| `hyprctl reload` \|
	157	+\| QML under `shell/` \| same pattern \| `omarchy-restart-shell` \|
	158	+\| a user dotfile template \| `omarchy-refresh-config <relpath>` \| immediate \|
	159	+
	160	+To test unreleased UI ad hoc, run it straight from the checkout — e.g. `quickshell -p ~/de-omarchy/plugin-library` — without touching the installation.
	161	+
	162	+## Repository layout
	163	+
65	164	```
66	165	de-omarchy/
67		- install.sh # idempotent installer
68		- uninstall.sh # full rollback
69		- shell/ # vendored Quickshell UI
70		- themes/ # 22 themes
71		- bin/ # omarchy-* commands
72		- default/ # hypr runtime, templates, fonts
73		- config/ # user-side hooks (hypr layer, zsh, PAM)
74		- scripts/ # backup, verify, migrate, scan-secrets
75		- packages/ # curated UI-only package list
76		- audit/ # system analysis, conflict mapping
	166	+├── install.sh / uninstall.sh deploy / fully revert the layer
	167	+├── bin/ ~440 omarchy-* commands; router: bin/omarchy
	168	+├── shell/ Quickshell desktop: Commons/, Ui/, plugins/
	169	+│ └── plugins/ bar/, panels/, services/, notification-center/, …
	170	+├── default/ deployed defaults: hypr/ (Lua), themed/ (tpl), agents/skills/
	171	+├── config/ live-config hooks: hypr/, omarchy/shell.json, pam/, zshrc.d/
	172	+├── themes/ 22 × colors.toml
	173	+├── registry.json plugin catalog shown in the Plugin Library
	174	+├── monitor-manager/ standalone visual monitor arrangement app
	175	+├── plugin-library/ standalone Plugin Library window
	176	+├── keybindings/ KEYMAP.md + cheat-sheet window source
	177	+├── docs/ manual/ agents/ vendored upstream references (51-chapter manual included)
	178	+└── audit/PARITY-AUDIT.md fork-vs-upstream audit trail
77	179	```
78	180
79		-Runtime: `/usr/share/de-omarchy`. Env: `OMARCHY_PATH` via `/etc/environment.d`, `hl.env`, zsh hook.
	181	+## Documentation
	182	+
	183	+The full [Omarchy Manual](manual/) ships vendored — 51 chapters covering navigation, theming, plugins, updates, troubleshooting, and more. Start at [`manual/01-welcome-to-omarchy.md`](manual/01-welcome-to-omarchy.md). Fork-specific deltas live in [`docs/FORK-NOTES.md`](docs/FORK-NOTES.md); where the two disagree, FORK-NOTES wins.
80	184
81	185	## Credits
82	186
83		-[Omarchy](https://github.com/basecamp/omarchy) by David Heinemeier Hansson (MIT).
84		-Vendored components retain upstream MIT license — see `LICENSE.upstream`.
	187	+[Omarchy](https://github.com/basecamp/omarchy) by David Heinemeier Hansson and contributors (MIT). de-omarchy ports its UI, shell, and tooling for non-Omarchy Arch systems; vendored components retain the upstream license — see `LICENSE.upstream`.
85	188