Let shell plugins declare optional package dependencies

[jacob-vincent-mink]

ai;dr I'm working on a plugin that derives some optional functionality from a browser extension. Today, that functionality is injected into the system via the plugin's settings page (all quickshell jazz), and must be removed using the same settings page. If the user does not do this prior to removing the plugin, it leaves an orphaned browser extension.

Having reviewed some of the intentions behind the plugin system design, I understand the reasons why the plugin add/remove logic does not allow for any hooks - that being said, I hope this proposal for dependencies/optional dependencies can be considered as it will extend the plugin system meaningfully. Allowing omarchy plugin add/remove to inspect the manifest and handle package dependencies itself, in full view of the user, would help with the use case above. Further iterations with sol brought out an interesting option for auto-generating a meta-package for the plugin on install that seems to help resolve the dependency tracking issue nicely.

Enjoy the 5.6 sol write-up below, outline more of the details, tyty.

---

The gap

Omarchy shell plugins are intentionally simple to install:

omarchy plugin add https://github.com/example/plugin.git

The command clones and validates the repository without running installation hooks, invoking a package manager, or requesting elevated privileges. That is a valuable security boundary.

Some plugins may offer capabilities that require packages outside the plugin directory. Examples include:

• grim or another standard command-line utility
• A browser extension with a native companion
• Additional codecs or format support
• A local background service
• Hardware-specific tools

Today, plugin authors must bundle these dependencies, ask users to install them manually, or implement custom setup and removal flows.

Why checking whether a package is installed is insufficient

Suppose an existing Arch package already depends on grim:

existing-package → grim

A newly enabled Omarchy plugin also needs grim, but the plugin is a Git checkout rather than an Arch package. Pacman cannot see that relationship.

If existing-package is later removed with dependency cleanup, pacman can remove grim even though the plugin still needs it.

Omarchy could maintain its own dependency accounting, but pacman already has a dependency graph. The missing piece is representing the plugin inside that graph.

Proposal

Allow plugin manifests to declare required and optional packages. Omarchy would translate the accepted declarations into a generated, metadata-only Arch metapackage for that plugin.

An illustrative manifest might look like:

  {
    "omarchy": {
      "packages": {
        "required": ["grim"],
        "optional": [
          {
            "id": "browser-context",
            "label": "Browser context",
            "packages": ["example-browser-companion"]
          }
        ]
      }
    }
  }

After the user selects optional capabilities, Omarchy could generate the equivalent of:

  pkgname=omarchy-plugin-deps-example-plugin
  pkgver=1.2.0
  pkgrel=1
  pkgdesc="Dependencies for the example Omarchy plugin"
  arch=("any")
  depends=("grim" "example-browser-companion")

  package() {
    :
  }

The generated package would contain no executable code or installed files. It would exist only to give pacman a real dependency edge:

existing-package ──────────────────→ grim
omarchy-plugin-deps-example-plugin ─→ grim

Why a metapackage helps

Pacman would retain responsibility for dependency resolution and removal:

• If grim is already installed as a dependency, it is not reinstalled or promoted to explicitly installed.
• Removing existing-package keeps grim because the plugin metapackage still requires it.
• Multiple plugins can depend on grim without Omarchy implementing reference counting.
• Removing one plugin keeps packages still required by another plugin.
• Removing the final plugin metapackage can remove dependencies that have become unused.
• Packages explicitly installed by the user remain installed.

This avoids maintaining a second dependency graph inside Omarchy.

Suggested lifecycle

Add

omarchy plugin add would continue to:

1. Clone the repository.
2. Validate the manifest.
3. Leave the plugin disabled for review.

It would not install packages simply because the repository was cloned.

Enable

When enabling the plugin, Omarchy would:

1. Display required packages.
2. Present optional capabilities for selection.
3. Resolve each package against configured repositories.
4. Show the repository and version that would be installed.
5. Request confirmation before invoking pacman or sudo.
6. Generate and install the plugin metapackage.
7. Enable the plugin only after package installation succeeds.

omarchy plugin add --enable could perform both phases in one flow.

An example prompt:

This plugin requests:

Required:
grim extra/grim 1.4.1

Optional:
[x] Browser context
example-browser-companion omarchy/example-browser-companion 1.0.0

Install these capabilities? [Install / Cancel]

Disable

Disabling a plugin could retain its metapackage so re-enabling it does not require reinstalling dependencies.

Update

If a plugin update changes its dependency declaration, Omarchy would show that separately from the source diff.

After confirmation, it would regenerate and reinstall the metapackage with the new dependency list. Removed dependencies would then become eligible for pacman's normal orphan handling.

Remove

Plugin removal would:

1. Disable the plugin.
2. Remove its generated metapackage with dependency cleanup.
3. Delete the Git checkout only after the package operation succeeds.

Pacman would preserve dependencies still required by another package, another plugin metapackage, or an explicit user installation.

Optional capabilities

Optional capabilities could be represented by dependencies included in or omitted from the generated metapackage.

Enabling a capability would regenerate the metapackage with its packages included. Disabling it would regenerate the metapackage without them.

This could support a standard plugin Settings surface while keeping the capability lifecycle under Omarchy and pacman control.

Package sources

A first implementation could allow only packages available through configured pacman repositories, including official Arch repositories and the signed Omarchy repository.

It should not accept:

• Arbitrary shell commands
• Repository URLs
• Plugin-provided PKGBUILDs
• Install or uninstall scripts
• Unreviewed AUR recipes

Support for other sources could be considered separately.

Security properties

The metapackage must be generated entirely by trusted Omarchy code from validated manifest data.

Plugin manifests would provide only package names, supported version constraints, capability labels, and descriptions. They would not provide executable package-building content.

This preserves the current guarantee that adding a plugin does not silently execute installation code while still supporting richer integrations.

Failure and recovery

• A plugin should not be enabled if required dependency installation fails.
• Declining an optional capability should leave the plugin usable without it.
• Failed metapackage updates should leave the previous dependency package installed.
• Plugin removal should not delete the checkout if dependency cleanup fails unexpectedly.
• If a metapackage is removed manually, Omarchy should detect the missing dependencies before enabling or launching the plugin.

Open questions

• Should dependency installation happen only during plugin enable, or should plugin add offer it after review?
• How should optional capability choices be stored?
• Should changing optional capabilities be available through standard plugin Settings?
• How should metapackage versions change when only dependency declarations change?
• Should --yes install newly declared packages requiring sudo, or require a separate explicit flag?
• Should dependency removal happen automatically or remain a confirmation step?

This would let plugins remain small and safe by default while allowing users to enable richer integrations through a native, auditable package lifecycle.