swadhin / de-omarchy public

Redesign README: centered header, badge row, vector icon stack, GitHub alerts

swadhinbiswas committed 2 months ago
f9ebd67
1 parent 70bd3af
commit f9ebd67
1 file changed
+95 -72
Showing 1 changed file+95-71
README.md
▼README.md
+95-71
@@ -1,38 +1,56 @@
1
-# de-omarchy
1
+<h1 align="center">de&#8209;omarchy</h1>
2
+
3
+<p align="center">
4
+ <strong>The Omarchy desktop, layered onto any Arch-based system.</strong><br>
5
+ <sub>Hyprland + Quickshell shell, themes, plugins and ~440 CLI commands — installed additively over the Linux you already run.</sub>
6
+</p>
7
+
8
+<p align="center">
9
+ <a href="https://github.com/swadhinbiswas/de-omarchy/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-cba6f7?style=flat-square" alt="MIT license" /></a>
10
+ <a href="#installation"><img src="https://img.shields.io/badge/Arch%C2%B7based-Arch%20%7C%20CachyOS%20%7C%20EndeavourOS%20%7C%20Manjaro-1793D1?style=flat-square&amp;logo=archlinux&amp;logoColor=white" alt="Arch-based" /></a>
11
+ <a href="https://github.com/basecamp/omarchy"><img src="https://img.shields.io/badge/port%20of-Omarchy-4550e0?style=flat-square&amp;logo=github&amp;logoColor=white" alt="Port of Omarchy" /></a>
12
+ <a href="https://github.com/swadhinbiswas/de-omarchy/issues"><img src="https://img.shields.io/github/issues/swadhinbiswas/de-omarchy?style=flat-square&amp;color=d29922" alt="Open issues" /></a>
13
+</p>
14
+
15
+<p align="center">
16
+ <img src="https://cdn.simpleicons.org/hyprland/cba6f7" height="26" alt="Hyprland" />&nbsp;&nbsp;
17
+ <img src="https://cdn.simpleicons.org/wayland/cba6f7" height="26" alt="Wayland" />&nbsp;&nbsp;
18
+ <img src="https://cdn.simpleicons.org/archlinux/cba6f7" height="26" alt="Arch Linux" />&nbsp;&nbsp;
19
+ <img src="https://cdn.simpleicons.org/lua/cba6f7" height="26" alt="Lua" />&nbsp;&nbsp;
20
+ <img src="https://cdn.simpleicons.org/zsh/cba6f7" height="26" alt="zsh" />&nbsp;&nbsp;
21
+ <img src="https://cdn.simpleicons.org/neovim/cba6f7" height="26" alt="Neovim" />&nbsp;&nbsp;
22
+ <img src="https://cdn.simpleicons.org/starship/cba6f7" height="26" alt="Starship" />&nbsp;&nbsp;
23
+ <img src="https://cdn.simpleicons.org/docker/cba6f7" height="26" alt="Docker" />&nbsp;&nbsp;
24
+ <img src="https://cdn.simpleicons.org/git/cba6f7" height="26" alt="Git" />
25
+</p>
26
+
27
+<p align="center">
28
+ <a href="#installation"><img src="https://img.shields.io/badge/Install%20in%20minutes-2ea44f?style=for-the-badge" alt="Install" /></a>&ensp;
29
+ <a href="https://discord.gg/4fZ8fawe6"><img src="https://img.shields.io/badge/Join%20the%20Discord-5865F2?style=for-the-badge&amp;logo=discord&amp;logoColor=white" alt="Discord" /></a>&ensp;
30
+ <a href="manual/01-welcome-to-omarchy.md"><img src="https://img.shields.io/badge/Read%20the%20Manual-24292f?style=for-the-badge" alt="Manual" /></a>
31
+</p>
2
32
3
-**The Omarchy desktop, layered onto any Arch-based system.**
4
-
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
-
7
-Ported from Omarchy by DHH (MIT). See [Credits](#credits).
33
+---
8
34
9
-[Discord](https://discord.gg/4fZ8fawe6) · [Issue tracker](https://github.com/swadhinbiswas/de-omarchy/issues) · [Upstream Omarchy](https://github.com/basecamp/omarchy)
35
+de-omarchy takes the [Omarchy](https://github.com/basecamp/omarchy) experience — the bar, launcher, theming, notifications, lock screen, screensaver — and installs it as a **self-contained desktop layer** on top of your existing system. No ISO, no bootloader, no display manager, no mirrors touched. Everything it adds is additive, marked, and reversible.
10
36
37
+Your system stays yours. Your bindings win. Uninstalling puts everything back exactly as it was.
11
38
12
-## Highlights
39
+## At a glance
13
40
14
41
| | |
15
42
|---|---|
16
-| **Quickshell shell** | Bar, launcher, menus, notifications, clipboard, emojis, lock screen, OSD |
17
-| **10 bar styles** | Classic → Floating Islands → Glass → OLED Black… cycle live with `SUPER + CTRL + Y` |
18
-| **22 themes** | Live switching, `omarchy theme set "Tokyo Night"` |
19
-| **System monitor widget** | CPU, RAM, disk, GPU temp, network throughput — every 2 s, click for btop |
20
-| **Notification center** | Bell widget + history panel, `SUPER + ALT + N` |
21
-| **Plugin marketplace** | Browse and install community plugins from the Plugin Library (`SUPER + SHIFT + I`) |
22
-| **Monitor Manager** | Visual multi-monitor arrangement, `SUPER + CTRL + M` |
23
-| **Animated screensaver** | Terminal-text-effects engine, random effect each idle — exactly upstream |
24
-| **~440 CLI commands** | The full `omarchy-*` surface, routed through one `omarchy` entry point |
25
-| **Agent skills** | Ships Omarchy skills symlinked into Claude Code, Codex, Gemini, and friends |
26
-
27
-## Requirements
28
-
29
-- An **Arch-based distro** already running **Hyprland configured via Lua** (`hyprland.lua`)
30
-- [`quickshell`](https://quickshell.outfoxxed.me/) — repo package on Arch/CachyOS
31
-- `paru` or `yay` for the handful of AUR-only packages (e.g. `python-terminaltexteffects`, `xdg-terminal-exec`)
32
-- `git`, `rsync`, `curl`
33
-
34
-## Install
43
+| **Quickshell desktop** | Bar, launcher, menus, notifications, clipboard, emojis, lock screen, OSD |
44
+| **10 bar styles** | Classic → Floating Islands → Glass → OLED Black… cycle live with <kbd>SUPER</kbd>+<kbd>CTRL</kbd>+<kbd>Y</kbd> |
45
+| **22 themes** | One TOML file each; live switching across terminal, GTK, and shell |
46
+| **System monitor widget** | CPU, RAM, disk, GPU temp, network — sampled every 2 s, click opens btop |
47
+| **Notification center** | History panel + do-not-disturb, <kbd>SUPER</kbd>+<kbd>ALT</kbd>+<kbd>N</kbd> |
48
+| **Plugin marketplace** | Browse and install community plugins (<kbd>SUPER</kbd>+<kbd>SHIFT</kbd>+<kbd>I</kbd>) |
49
+| **Monitor Manager** | Visual multi-monitor arrangement, <kbd>SUPER</kbd>+<kbd>CTRL</kbd>+<kbd>M</kbd> |
50
+| **Animated screensaver** | Terminal-text-effects at 120 fps — the real upstream behavior |
51
+| **~440 CLI commands** | One `omarchy` entry point; every command self-documents for humans *and* AI agents |
52
+
53
+## Installation
35
54
36
55
```bash
37
56
git clone https://github.com/swadhinbiswas/de-omarchy.git ~/de-omarchy
@@ -40,38 +58,39 @@ cd ~/de-omarchy
40
58
41
59
./scripts/diff-preview.sh # dry run — see exactly what would change
42
60
./install.sh # targeted backup first, then apply
61
+hyprctl reload # or log out and back in
43
62
```
44
63
45
-Then `hyprctl reload` — or log out and back in so environment variables settle everywhere.
64
+> [!TIP]
65
+> Already installed and re-running later? The installer preserves your current theme, skips packages you already have, and refreshes the runtime — then tells you to run `omarchy-restart-shell`.
46
66
47
-### What the installer does, in order
67
+**What the installer does, in order:**
48
68
49
69
1. **Backs up** every file it could touch (plus `.ssh`, zsh stack, starship) to `~/.de-omarchy-backups/<timestamp>/`
50
70
2. Installs **missing UI packages only** — never upgrades what you have
51
-3. Deploys the runtime to **`/usr/share/de-omarchy`** (`rsync -a --delete` of `bin/ shell/ themes/ default/ config/ …`)
52
-4. Installs **additive hooks**: three symlinks into `~/.config/hypr/`, one into `~/.config/zshrc.d/` — all pointing at *runtime copies*, never at your git checkout
53
-5. Appends **one clearly-marked block** to `~/.config/hypr/hyprland.lua` (pre-change copy saved next to it)
54
-6. Initializes Omarchy state and applies the rose-pine theme
71
+3. Deploys the runtime to **`/usr/share/de-omarchy`**
72
+4. Installs four **additive hooks** — symlinks into `~/.config/hypr/` and `~/.config/zshrc.d/`, pointing at *runtime copies*, never at your git checkout
73
+5. Appends **one clearly-marked block** to `hyprland.lua` (pre-change copy saved beside it)
74
+6. Initializes state and applies a default theme on first install only
55
75
56
-Idempotent: safe to re-run any time.
76
+Idempotent. Safe to re-run any time.
57
77
58
-### The safety contract
78
+> [!IMPORTANT]
79
+> **The safety contract**
80
+>
81
+> **Never touched:** `pacman.conf`, mirrors, repos, kernel, bootloader, display manager, monitors layout, `.zshrc`, `.zshenv`, `starship.toml`, `kitty.conf`, SSH keys. Nothing in `$HOME` is deleted or overwritten.
82
+>
83
+> **Added:** the runtime dir, the four symlinks, the marked Hyprland block, `/etc/environment.d/10-de-omarchy.conf`, a PAM stanza for the lock screen, and `/usr/bin` symlinks for a dozen commands.
59
84
60
-**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.
61
-
62
-**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`.
63
-
64
-## Uninstall
85
+To undo completely:
65
86
66
87
```bash
67
-./uninstall.sh
88
+./uninstall.sh # then restore anything else from ~/.de-omarchy-backups/<timestamp>/
68
89
```
69
90
70
-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`.
71
-
72
91
## Keybindings
73
92
74
-Your existing bindings win — de-omarchy only claims keys that are free. The essentials:
93
+Your existing bindings win — de-omarchy only claims keys that are free.
75
94
76
95
| Key | Action |
77
96
|---|---|
@@ -81,17 +100,17 @@ Your existing bindings win — de-omarchy only claims keys that are free. The es
81
100
| <kbd>SUPER</kbd> + <kbd>ALT</kbd> + <kbd>N</kbd> | Notification center |
82
101
| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>M</kbd> | Monitor Manager |
83
102
| <kbd>SUPER</kbd> + <kbd>SHIFT</kbd> + <kbd>I</kbd> | Plugin Library |
84
-| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>A</kbd> / <kbd>B</kbd> / <kbd>W</kbd> | Audio / Bluetooth / Network panel |
103
+| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>A</kbd>/<kbd>B</kbd>/<kbd>W</kbd> | Audio / Bluetooth / Network panel |
85
104
| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>SPACE</kbd> | Background switcher |
86
105
| <kbd>SUPER</kbd> + <kbd>PRINT</kbd> / <kbd>ALT</kbd> + <kbd>PRINT</kbd> | Screenshot / screen recording |
87
106
| <kbd>SUPER</kbd> + <kbd>CTRL</kbd> + <kbd>T</kbd> | Activity (btop) |
88
-| <kbd>SUPER</kbd> + <kbd>grave</kbd> | Scratchpad |
107
+| <kbd>SUPER</kbd> + <kbd>`</kbd> | Scratchpad |
89
108
90
-Full map, including preserved host bindings and documented conflict decisions: [`keybindings/KEYMAP.md`](keybindings/KEYMAP.md).
109
+<sub>The full map — including preserved host bindings and every conflict decision — lives in [`keybindings/KEYMAP.md`](keybindings/KEYMAP.md).</sub>
91
110
92
111
## The CLI
93
112
94
-One router, ~440 self-documenting commands:
113
+One router, ~440 self-documenting commands. Every command carries machine-readable metadata (`# omarchy:summary=…`), so `--help`, menus, and AI agents all read the same source of truth.
95
114
96
115
```console
97
116
$ omarchy --help # grouped, searchable command index
@@ -100,27 +119,19 @@ $ omarchy theme set catppuccin # live switch
100
119
$ omarchy bar style list # the 10 bar presets
101
120
$ omarchy bar style set glass # repaint the bar
102
121
$ omarchy plugins marketplace # browse the community catalog
103
-$ omarchy plugin add <git-url> # sideload a plugin
122
+$ omarchy plugins install <name> # install a plugin headlessly
104
123
$ omarchy shell toggle omarchy.audio # IPC into the running shell
105
124
```
106
125
107
-Every command carries machine-readable metadata (`# omarchy:summary=…`), so `--help`, menus, and AI agents all read the same source of truth.
126
+## Plugins
108
127
109
-## Shell plugins
128
+Plugins are Quickshell components with a `manifest.json`; kinds are `bar-widget`, `panel`, or `service`. First-party plugins ship inside the runtime and load automatically. User-installed ones live in `~/.config/omarchy/plugins/` and merge in at scan time — anything under the reserved `omarchy.*` namespace always resolves to the first-party version.
110
129
111
-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).
112
-
113
-Open **Plugin Library** (`SUPER + SHIFT + I`) to browse the bundled catalog plus the [omarchyplugins.com](https://omarchyplugins.com) marketplace, or drive it headless:
114
-
115
-```console
116
-$ omarchy plugins list
117
-$ omarchy plugins install docker-status
118
-$ omarchy-shell shell setPluginEnabled deomarchy.power-profile true
119
-```
130
+Open **Plugin Library** (<kbd>SUPER</kbd>+<kbd>SHIFT</kbd>+<kbd>I</kbd>) for a GUI over the bundled catalog plus the [omarchyplugins.com](https://omarchyplugins.com) marketplace.
120
131
121
132
## Themes
122
133
123
-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:
134
+Each theme is one file — `themes/<name>/colors.toml`. Templates consume its variables and render into your terminal, GTK, and shell configs at switch time. Making a theme is making one TOML file:
124
135
125
136
```bash
126
137
cp -r themes/rose-pine themes/my-theme && $EDITOR themes/my-theme/colors.toml
@@ -129,7 +140,7 @@ omarchy theme set my-theme
129
140
130
141
## Screensaver
131
142
132
-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.
143
+The real Omarchy screensaver: your branding art rendered by [terminal-text-effects](https://github.com/ChrisBuilds/terminaltexteffects) at 120 fps, a random effect each 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.
133
144
134
145
## Architecture
135
146
@@ -145,21 +156,21 @@ The real Omarchy screensaver: your branding art rendered by [terminal-text-effec
145
156
Three layers, one direction of truth:
146
157
147
158
- **Source repo** — where you edit. Never referenced at runtime.
148
-- **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.
149
-- **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.
159
+- **Runtime** (`OMARCHY_PATH`) — the authoritative copy every process reads: Hyprland Lua modules, the Quickshell shell, all `omarchy-*` commands, plugin manifests.
160
+- **Live config** — `~/.config/hypr/deo-*.lua` are *override slots*: plain symlinks you may replace with your own files. Modules resolve `~/.local/state/` → `~/.config/` → `$OMARCHY_PATH/`, so user state beats fork defaults beats nothing.
150
161
151
162
Because the runtime is authoritative, deleting or breaking the source checkout cannot hurt a running desktop.
152
163
153
-### Deploy loop for development
164
+### Development loop
154
165
155
166
| You changed | Deploy | Apply |
156
167
|---|---|---|
157
168
| a `bin/omarchy-*` script | `sudo cp bin/omarchy-x /usr/share/de-omarchy/bin/` | nothing needed |
158
-| Hyprland Lua (`default/hypr/`, `config/hypr/`) | same pattern into `runtime/<same path>` | `hyprctl reload` |
169
+| Hyprland Lua (`default/hypr/`, `config/hypr/`) | same pattern into the runtime | `hyprctl reload` |
159
170
| QML under `shell/` | same pattern | `omarchy-restart-shell` |
160
171
| a user dotfile template | `omarchy-refresh-config <relpath>` | immediate |
161
172
162
-To test unreleased UI ad hoc, run it straight from the checkout — e.g. `quickshell -p ~/de-omarchy/plugin-library` — without touching the installation.
173
+To try unreleased UI without touching the installation, run it straight from the checkout — e.g. `quickshell -p ~/de-omarchy/plugin-library`.
163
174
164
175
## Repository layout
165
176
@@ -176,7 +187,7 @@ de-omarchy/
176
187
├── monitor-manager/ standalone visual monitor arrangement app
177
188
├── plugin-library/ standalone Plugin Library window
178
189
├── keybindings/ KEYMAP.md + cheat-sheet window source
179
-├── docs/ manual/ agents/ vendored upstream references (51-chapter manual included)
190
+├── docs/ manual/ agents/ vendored references (51-chapter manual included)
180
191
└── audit/PARITY-AUDIT.md fork-vs-upstream audit trail
181
192
```
182
193
@@ -186,8 +197,20 @@ The full [Omarchy Manual](manual/) ships vendored — 51 chapters covering navig
186
197
187
198
## Community
188
199
189
-Questions, screenshots, theme shares, and help live on the **[de-omarchy Discord](https://discord.gg/4fZ8fawe6)** — it's the fastest way to reach people. Bug reports and feature requests belong on the [issue tracker](https://github.com/swadhinbiswas/de-omarchy/issues); GitHub has templates for bugs, installation problems, and features. Anything that reproduces in upstream Omarchy itself should go to [upstream](https://github.com/basecamp/omarchy) instead.
200
+Questions, screenshots, theme shares, and help live on the **[de-omarchy Discord](https://discord.gg/4fZ8fawe6)** — usually faster than an issue for "how do I…" questions. Bug reports and feature requests belong on the [issue tracker](https://github.com/swadhinbiswas/de-omarchy/issues); templates are provided for bugs, installation problems, and features. Anything that reproduces in upstream Omarchy itself should go [upstream](https://github.com/basecamp/omarchy) instead.
201
+
202
+Before committing, run `scripts/scan-secrets.sh` — it's wired up as a pre-commit hook and blocks secrets or personal paths from entering history.
190
203
191
-## Credits
204
+---
192
205
193
-[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`.
206
+<p align="center">
207
+ <a href="https://discord.gg/4fZ8fawe6"><img src="https://cdn.simpleicons.org/discord/5865F2" height="22" alt="Discord" /></a>&nbsp;&nbsp;&nbsp;
208
+ <a href="https://github.com/swadhinbiswas/de-omarchy/issues"><img src="https://cdn.simpleicons.org/github/e6edf3" height="22" alt="GitHub issues" /></a>&nbsp;&nbsp;&nbsp;
209
+ <a href="https://github.com/basecamp/omarchy"><img src="https://cdn.simpleicons.org/archlinux/cba6f7" height="22" alt="Upstream Omarchy" /></a>
210
+</p>
211
+
212
+<p align="center">
213
+ <sub>[Omarchy](https://github.com/basecamp/omarchy) by David Heinemeier Hansson and contributors, MIT.<br>
214
+ de-omarchy ports its UI, shell, and tooling for non-Omarchy Arch systems.<br>
215
+ Vendored components retain the upstream license — see <a href="LICENSE.upstream">LICENSE.upstream</a>.</sub>
216
+</p>
194
217