# Omarchy Plugins and the Marketplace > What an Omarchy plugin really is, why it runs with all your access, how to judge one before you install it, the real omarchy plugin commands, and a worked install of The Missing Manual plugin. --- # Omarchy Plugins and the Marketplace A phone app or a browser extension runs in a sandbox, with permission prompts in front of it. On Omarchy, the bar at the top of your screen, the menu you open with `Super + Space`, and the lock screen are all plugins, and the plugins you add from the internet get no such sandbox. They run as you. That sounds alarming and is manageable once you know the model. This guide explains what a plugin is, how to decide whether to trust one, the commands that manage them, and walks through installing a real one end to end. Checked against Omarchy 4.0.4. ## Prerequisite You should be comfortable opening a terminal and running commands. If not, start with [The Terminal and Shell](/guides/the-terminal-and-shell). It also helps to know what the Omarchy menu and the `omarchy` command are: see [Omarchy Menus, Panels and the CLI](/guides/omarchy-menus-panels-and-cli). ## How to read this - **Want to install something right now?** Read [Phase 2](02-finding-judging-and-managing-plugins.md) first for the review habit and the commands, then [Phase 3](03-worked-example-the-missing-manual-plugin.md). - **Want it to make sense?** Read in order. The trust model in Phase 1 is the reason every later step looks the way it does. ## The phases 1. **[What a Plugin Is, and What It Can Reach](01-what-a-plugin-is-and-what-it-can-reach.md)** - one shell process, plugin kinds, and the plain truth about trust. 2. **[Finding, Judging, and Managing Plugins](02-finding-judging-and-managing-plugins.md)** - the marketplace, a review checklist, and every `omarchy plugin` command. 3. **[Worked Example: The Missing Manual Plugin](03-worked-example-the-missing-manual-plugin.md)** - review, enable, and remove a real plugin, and see what removal leaves behind. Daily use of it has its own guide, [The Missing Manual on Omarchy](/guides/the-missing-manual-on-omarchy). Writing your own plugin is a separate skill, covered in [Building Your Own Omarchy Plugin](/guides/building-your-own-omarchy-plugin). If a plugin misbehaves, [When Omarchy Breaks](/guides/when-omarchy-breaks) is the recovery guide. --- # What a Plugin Is, and What It Can Reach You press `Super + Space` and a menu appears. You glance at the bar and see a clock and a row of status icons. Each of those is a plugin. Once you see that, "adding a plugin" stops being mysterious: you are adding one more piece to the same machinery that draws your desktop. The second half of this phase is the part that matters for your safety: what a plugin you did not write is allowed to do. ## One process, many plugins Omarchy's desktop runs as a single long-lived process called `omarchy-shell`, built on Quickshell. Almost everything you see on screen is a plugin inside it: - the bar and the panels that drop down from it - fullscreen overlays such as the emoji picker and the clipboard manager - the Omarchy menu itself - the lock screen and the dialog that asks for your password - headless services that watch your battery or warm the screen at night ```mermaid flowchart TD S["omarchy-shell (one process)"] --> B["Bar and panels"] S --> M["Omarchy menu"] S --> O["Overlays"] S --> V["Background services"] S --> T["Your third-party plugin"] ``` This design is why you can turn pieces of the desktop off, swap them, or add your own without touching Omarchy's source. It is also why a plugin is not a separate program: it is code loaded into the process that draws your screen. ## Two places plugins live | Kind of plugin | Where it lives | Who owns it | |---|---|---| | First-party (ships with Omarchy) | `$OMARCHY_PATH/shell/plugins/` | Omarchy's package | | Third-party (yours or from the internet) | `~/.config/omarchy/plugins//` | You | Both are discovered at startup. Do not edit files under `$OMARCHY_PATH`: they belong to the package and the next update overwrites them. If you want to change a built-in, you clone it into your own folder instead (that is the first step of [Building Your Own Omarchy Plugin](/guides/building-your-own-omarchy-plugin)). Every plugin has an `id`. Built-ins start with `omarchy.`, such as `omarchy.clock` and `omarchy.network`. That prefix is reserved: a third-party plugin cannot claim it. ## The six kinds A plugin declares what it is in its manifest. The shell knows six kinds: | Kind | What it is | |---|---| | `bar-widget` | A component the bar drops into one of its sections | | `panel` | A floating window, persistent or summoned | | `overlay` | A fullscreen surface | | `menu` | A summoned menu surface | | `service` | A headless singleton with no visible UI | | `bar` | A full replacement for the built-in bar | One plugin can be several kinds at once. The built-in media plugin is both a `service` and a `bar-widget`. ## What a plugin can reach Here is the plain version, in the manual's own framing: plugins run as arbitrary, unsandboxed code, with everything your user account can reach. Your user account can read your home folder, your SSH keys, your browser profile, and your documents. A plugin is code your user runs, so it can too. There is no permission prompt standing between a plugin and your files. Omarchy does add a few guard rails, and it is worth knowing exactly what they are and are not: - Third-party plugins get a limited interface scoped to their own service and lifecycle, not the full trusted interface that built-ins receive. - Since 4.0.3, the third-party interface does not directly expose authentication services, and authentication state is kept outside the objects a plugin can reach. - The installer itself never runs plugin code, never runs an install hook, and never asks for `sudo`. It copies files, checks the manifest, and flips an enabled bit. > ⚠️ **Gotcha.** These are API boundaries, not a sandbox. Visual plugins share the shell's scene and can walk ordinary parent objects, so the manual's advice stands: only add repos you are willing to run, and read them before you enable them. The marketplace does not change this. Its own publishing page says it validates listings, not plugin security. ## Installed does not mean running A plugin that was added but not enabled is a folder on disk. The installer clones a repository, validates its manifest, and moves it into `~/.config/omarchy/plugins//`. It enables the plugin only if you pass `--enable` or answer yes to its "Enable now?" prompt. That gap is your review window, and the next phase uses it. How does Omarchy know a third-party plugin is enabled? The rule is plain: a third-party plugin is on exactly when its `id` appears somewhere in `~/.config/omarchy/shell.json`, as a bar layout entry, as an entry in `plugins[]`, or as `bar.id`. Built-in non-bar plugins work the other way around: they are on by default and off only when listed in `disabledPlugins[]`. A full `bar` plugin has no off state. There is always exactly one bar, so you replace it by enabling another one, and the built-in `omarchy.bar` is the safe path home. Check yourself before moving on: ```quiz [ { "q": "A friend shares a git URL for an Omarchy plugin. What is the most accurate description of what it can do once enabled?", "choices": [ "Nothing outside its own folder, because Omarchy sandboxes third-party plugins", "It runs inside your shell process as your user, so it can reach whatever your user account can reach", "It can only draw things on screen and cannot touch files", "It runs as root so it can change system settings" ], "answer": 1, "explain": "Plugins are unsandboxed code in the long-running shell process. The scoped interfaces limit which shell services a third-party plugin can ask for, but they are not a sandbox around your files.", "why": ["Third-party plugins are explicitly unsandboxed.", null, "Visual plugins share the shell's scene and run ordinary code with your user's access; they are not limited to drawing.", "The installer never asks for sudo and the shell runs as your user, not root."] }, { "q": "Where does a plugin you add from git end up?", "choices": [ "$OMARCHY_PATH/shell/plugins/", "/usr/share/omarchy/", "~/.config/omarchy/plugins//" ], "answer": 2, "explain": "Third-party plugins live under your config directory. The first-party folder belongs to Omarchy's package and gets overwritten by updates." }, { "q": "Which plugin id could never belong to a third-party plugin?", "choices": ["tmm.manual", "omarchy.weather", "io.github.yourname.custom-clock"], "answer": 1, "explain": "The omarchy. prefix is reserved for built-ins, and the validator refuses it." } ] ``` ## Recap 1. Omarchy's desktop is one `omarchy-shell` process, and the bar, menu, overlays, lock screen, and services are plugins inside it. 2. Built-ins live in `$OMARCHY_PATH/shell/plugins/`; your own and downloaded plugins live in `~/.config/omarchy/plugins//`. 3. A manifest declares one or more of six kinds: `bar-widget`, `panel`, `overlay`, `menu`, `service`, `bar`. 4. Third-party plugins are unsandboxed and run with everything your user account can reach; the scoped interfaces are guard rails, not a sandbox. 5. Added is not enabled: the installer never runs plugin code, and a third-party plugin is on exactly when its id appears in `shell.json`. Next up, [Finding, Judging, and Managing Plugins](02-finding-judging-and-managing-plugins.md): where plugins come from, how to read one before you trust it, and the commands that manage them. --- # Finding, Judging, and Managing Plugins Because a plugin runs with your access (Phase 1), the skill that matters is not the install command. It is deciding what deserves to be installed, and knowing how to take it back out. The commands are short; the habit is the lesson. ## Where plugins come from A plugin is a git repository with a `manifest.json` at its root. That is the whole distribution mechanism: anyone can publish one, and anyone can run `omarchy plugin add` against its URL. To find them, use the community marketplace at [plugins.omarchy.org](https://plugins.omarchy.org). You can browse and search, sort by recently added, most starred, most viewed, most copied, install rate, or verified and unverified, and copy the install command from a listing. The marketplace's source repository is `omacom/omarchy-plugin-marketplace`. What does a listing guarantee? Automated checks validate the plugin's current commit and a maintainer approves the listing. The marketplace's own words on what that covers: it validates listings, not plugin security. A listing tells you the plugin passed the marketplace's automated checks and a maintainer approved it. It does not tell you the code is safe. ## Judge before you enable Treat a plugin the way you would treat a script a stranger asks you to run, because that is what it is. This checklist is our advice, built from what the official docs say plugins can do: 1. **Who and where.** Is the repository public, with a real README and a license? Does the author's other work look real? 2. **What it claims.** Does the README document every external dependency, setup step, privilege, service, installer, or remote build? The official development guide asks authors to document exactly these, so a plugin that does not is skipping something it was asked to do. 3. **What it declares.** Open `manifest.json`. The `kinds` tell you where it runs: a `service` is headless and never shows a window, which makes it worth extra care. 4. **What else is in the repo.** A plugin is not only QML. Plugins can ship helper scripts (the example in Phase 3 has a `bin/` folder), and those run as you too. Read every script. 5. **What it talks to.** Search the code for network calls and for anything that launches commands: ```bash cd ~/.config/omarchy/plugins/ grep -rniE "curl|wget|sudo|ssh|http" . ls -R . ``` 6. **Does it ask for more than its job needs?** A clock that wants the network, or a weather widget that wants `sudo`, is a red flag. > 💡 **Key point.** You can read the code before it runs. `omarchy plugin add` clones the repo and validates it, but does not run any of it. If you do not pass `--enable`, the plugin sits on disk, disabled, until you decide. ## The review-first install ```bash omarchy plugin add https://github.com/acme/omarchy-weather.git ``` *What just happened:* Omarchy warned you that plugins run as arbitrary, unsandboxed code inside your shell process, showed the URL, and asked you to confirm. Then it cloned the repo into a staging folder, validated the manifest, refused if the id was already in use, moved it into `~/.config/omarchy/plugins//`, and rescanned. It then asks "Enable now?". Answer no, go read the folder, and enable it when you are satisfied. The URL check also refuses a URL that names a git option or a transport helper, so a malicious "URL" cannot run a command before the plugin is validated. That protects the clone step. It does not make the plugin's own code safe. ## The command set Every command below is a real `omarchy plugin` subcommand at 4.0.4. | Command | What it does | |---|---| | `omarchy plugin list` | Prints every discovered plugin: id, enabled state, first- or third-party, kinds, name. Add `--json` for machines. | | `omarchy plugin add [--enable] [--yes]` | Clones, validates, installs. Alias: `omarchy plugin install`. | | `omarchy plugin enable ` | Turns a plugin on. | | `omarchy plugin disable ` | Turns a plugin off. | | `omarchy plugin update [id] [--yes]` | Updates one git-managed plugin, or all of them when you give no id. | | `omarchy plugin remove [id] [--yes]` | Disables, then deletes a plugin. Alias: `omarchy plugin rm`. | | `omarchy plugin clone [--edit]` | Copies a built-in into your own folder (see the building guide). | | `omarchy plugin validate ` | Checks a folder against the manifest rules. | You can do the same from the menu. Press `Super + Space`, then choose _Setup > Plugins_: it offers Enable, Disable, Add, Clone, and Remove, and each picker lists only the plugins that make sense for that action. ### Updating safely ```bash omarchy plugin update acme.weather omarchy plugin update ``` Updating is a fast-forward pull of the plugin's git checkout. Omarchy shows you the diff before applying it, refuses if you have local changes it cannot fast-forward past, and rolls back if the new revision fails validation. Read that diff. A plugin you reviewed last month can change under you, and the diff is your chance to review the change. ### Removing ```bash omarchy plugin remove acme.weather ``` Removal disables the plugin first, then deletes it. If it is a git checkout, the repo is still upstream, so nothing is lost. If it is a symlink, the link is unlinked. A hand-made folder with no git repo is moved to a timestamped backup inside the plugins directory instead of being deleted outright. If the plugin left things outside its own folder (a menu row, a keybinding, a script in `~/.local/bin`), those are yours to clean up. The next phase shows a real example of that. ### Scripts and AI agents `add`, `update`, and `remove` ask for confirmation in a terminal even when you give arguments. Without a terminal they refuse rather than guess. `--yes` skips every prompt and is the path for scripts. Use it only when you have already decided to trust the plugin. ## When a plugin does not show up After adding or hand-copying files, force the shell to look again: ```bash omarchy-shell shell rescanPlugins ``` Saving any file under `~/.config/omarchy/plugins/` also reloads plugin code automatically. If a reload does not seem to take, `omarchy restart shell` is the stronger reset. A common cause of "it does nothing" is that the plugin was added but never enabled, so check `omarchy plugin list` first. [When Omarchy Breaks](/guides/when-omarchy-breaks) covers deeper recovery. An installed plugin is a plain git checkout of its repository, so [Git From Zero](/guides/git-from-zero) explains what `update` is doing underneath. Check yourself before moving on: ```quiz [ { "q": "A plugin is listed on the marketplace. What does that tell you?", "choices": [ "The code was security audited and is safe to run", "Its listing passed automated validation and a maintainer approved it, but the marketplace does not vouch for the plugin's security", "Omarchy sandboxes it, so reviewing the code is optional" ], "answer": 1, "explain": "The marketplace validates listings, not plugin security. Plugins run unsandboxed whether or not they are listed." }, { "q": "You want to read a plugin's code before it ever runs. Which approach fits?", "choices": [ "omarchy plugin add --enable --yes, then read it afterwards", "omarchy plugin add , answer no to Enable now, read the folder under ~/.config/omarchy/plugins/, then omarchy plugin enable ", "Copy the files in by hand and reboot" ], "answer": 1, "explain": "Adding without enabling clones and validates but runs nothing. Enable only after you have read it.", "why": ["That enables it immediately, with no prompts and no chance to read first.", null, "Hand-copied plugins also start disabled, but rebooting is unnecessary and this skips the review habit entirely."] }, { "q": "omarchy plugin update acme.weather finds that the new revision fails validation. What happens?", "choices": [ "The broken version is kept so you can debug it", "It rolls back to the previous revision", "The plugin is removed" ], "answer": 1, "explain": "Update shows the diff first, refuses if local changes block a fast-forward, and rolls back if the new revision fails validation." } ] ``` ## Recap 1. A plugin is a git repo with a `manifest.json`; the marketplace at plugins.omarchy.org is a directory of them. 2. A listing means the manifest validated and a maintainer approved it, not that the code is safe. 3. Review before enabling: README, manifest kinds, helper scripts, network calls, and anything that asks for more than its job needs. 4. `omarchy plugin add` runs nothing; `--enable` is the only thing between adding and running, so leave it off until you have read the code. 5. The command set is `list`, `add`, `enable`, `disable`, `update`, `remove`, with `clone` and `validate` for authors; `Setup > Plugins` is the menu equivalent. 6. `update` shows a diff and rolls back on failure; `remove` disables first and never silently discards a hand-made folder. Next up, [Worked Example: The Missing Manual Plugin](03-worked-example-the-missing-manual-plugin.md): review, install, and use a real plugin from start to finish. --- # Worked Example: The Missing Manual Plugin Everything so far has been principle. Here is one real plugin, installed the careful way. It is [omarchy-tmm](https://github.com/Topurrra/omarchy-tmm), plugin id `tmm.manual`, which brings The Missing Manual (this library) into Omarchy as a window you can open with a keystroke. The version we checked is 0.5.0. This phase uses it to practice the habits from Phase 2: review, enable, and know what removal leaves behind. Hotkeys, the menu entry, and daily use have their own guide, [The Missing Manual on Omarchy](/guides/the-missing-manual-on-omarchy). ## What it is A native Omarchy 4 plugin made of three kinds: a `panel` (the reader window), a `service` (a headless search and cache service), and a `bar-widget` (a book button in the bar). It also ships a terminal command, `tmm`, that renders the same guides in your terminal. It requires Omarchy 4 and does not work on 3.x. What does it talk to? Only the public endpoints of themissingmanual.dev, such as search and the guide text. Its README says it never uploads anything about you: a search sends your query, an Ask question sends your question, and nothing else. ## Step 1: review it first You know the drill from Phase 2. Add it without `--enable`: ```bash omarchy plugin add https://github.com/Topurrra/omarchy-tmm.git ``` Answer no to "Enable now?". Then read the folder: ```bash ls ~/.config/omarchy/plugins/tmm.manual/ cat ~/.config/omarchy/plugins/tmm.manual/manifest.json ls ~/.config/omarchy/plugins/tmm.manual/bin/ ``` *What just happened:* the repo is on disk and the manifest validated, but nothing has run. You will see `Panel.qml`, `Service.qml`, `BarWidget.qml`, and a `bin/` folder of helper scripts such as `tmm`, `tmm-cap`, `tmm-diagrams`, and `tmm-menu`. Those scripts are why the review matters: they run as you. `Service.qml` is where every network address is built, so it is the file to read if you want to confirm the "public endpoints only" claim yourself. ## Step 2: enable it Once you have read it, enable it and let the shell pick it up: ```bash omarchy plugin enable tmm.manual omarchy-shell shell rescanPlugins ``` The one-line install, `omarchy plugin add https://github.com/Topurrra/omarchy-tmm.git --enable`, adds and enables in a single step. It is the shortcut for people who have already reviewed the code. Run in a terminal, it may first ask which bar section to place the widget in; the plugin's default is the right side. A book glyph should appear in the bar. Click it to toggle the window. If it does not appear, place it by hand: ```bash omarchy bar put tmm.manual --section right ``` > ⚠️ **Gotcha.** A disabled plugin answers a summon by doing nothing at all, which looks exactly like a broken install. If a keystroke or menu entry does nothing, check `omarchy plugin list` for the enabled state before anything else. ## Everything after that is opt-in `omarchy plugin add` only puts files in the plugins folder. It never runs plugin code, install hooks, or `sudo`. So anything a plugin wants outside its own folder, such as a hotkey in `~/.config/hypr/bindings.lua`, a row in the Omarchy menu, or a command on your `PATH`, is a step you take yourself, on purpose. For tmm.manual those steps are a hotkey, a menu entry, and the `tmm` terminal command. [The Missing Manual on Omarchy](/guides/the-missing-manual-on-omarchy) walks through each one, including two lines in the plugin's own install notes that do not work as written on Omarchy 4.0.4. ## Removing a plugin, and what it leaves behind `omarchy plugin disable tmm.manual` turns it off and keeps the files. `omarchy plugin remove tmm.manual` asks for confirmation, disables the plugin, and deletes its folder. What remove does not touch is everything you set up outside that folder: hotkey lines in `bindings.lua`, menu rows, copied commands, and any cache or state the plugin wrote while it ran. That is true of every plugin, not only this one. Before you remove a plugin, undo the extras you added (for tmm.manual, the removal steps are in the guide above), then remove it. If a plugin's window does not appear at all, the debugging order works for any plugin: confirm it is enabled with `omarchy plugin list`, rescan with `omarchy-shell shell rescanPlugins`, then summon it. If the summon prints `ok` but nothing shows, the plugin's QML failed to draw. The shell logs to the journal, so look there: ```bash journalctl -t omarchy-shell -n 100 --no-pager ``` Check yourself before moving on: ```quiz [ { "q": "You ran omarchy plugin add for tmm.manual without --enable, then pressed its hotkey and nothing happened. What is the most likely cause?", "choices": [ "The plugin is broken and must be reinstalled", "The plugin is installed but disabled, and a disabled plugin ignores a summon", "Omarchy blocks hotkeys from third-party plugins" ], "answer": 1, "explain": "Plugins stay disabled unless you pass --enable or confirm the prompt. Run omarchy plugin enable tmm.manual, then rescan." }, { "q": "Why add a plugin without --enable first?", "choices": [ "It installs faster", "The files land on disk but nothing runs yet, so you can read the manifest and scripts before they run as you", "Plugins added with --enable cannot be removed later" ], "answer": 1, "explain": "A plugin runs with your user's access. Adding it disabled gives you a window to review the code before any of it executes." }, { "q": "After omarchy plugin remove tmm.manual, what can still be left on your machine?", "choices": [ "Nothing, remove deletes everything the plugin ever created", "Anything set up outside the plugin folder, such as hotkey lines, menu rows, copied commands, and its cache", "Only the plugin folder itself" ], "answer": 1, "explain": "Remove deletes the plugin's own folder. Hotkeys, menu rows, and files outside that folder are yours to clean up, ideally before removing the plugin." } ] ``` ## Recap 1. `tmm.manual` is a panel, service, and bar widget plugin that needs Omarchy 4; it reads only public themissingmanual.dev endpoints. 2. Review first: `omarchy plugin add ` without `--enable`, read the manifest, `bin/`, and `Service.qml`, then `omarchy plugin enable tmm.manual` and rescan. 3. A disabled plugin ignores summons silently, so check `omarchy plugin list` first when nothing happens. 4. Adding a plugin never touches your config; hotkeys, menu rows, and commands are opt-in steps you take yourself. 5. `omarchy plugin remove` deletes only the plugin folder, so undo the extras first. Ready to make your own? [Building Your Own Omarchy Plugin](/guides/building-your-own-omarchy-plugin) uses this same plugin as a structural reference. For using tmm.manual every day, see [The Missing Manual on Omarchy](/guides/the-missing-manual-on-omarchy).