How to Clone a Built‑in Omarchy Plugin to Your User Configuration

Run omarchy plugin clone <plugin-id> to copy any built‑in plugin from $OMARCHY_PATH/shell/plugins to your personal ~/.config/omarchy/plugins/ directory, where it receives a unique user‑prefixed identifier and full editing freedom without modifying system files.

Omarchy, the open‑source desktop environment maintained by Basecamp, stores its first‑party plugins in a protected system path that remains untouched during upgrades. When you need to customize a built‑in plugin’s behavior or appearance, you must clone the Omarchy plugin into your user configuration space rather than editing the originals directly.

Where Built‑in Plugins Live

Omarchy ships with core plugins located under $OMARCHY_PATH/shell/plugins. These files are read‑only from the user perspective and update automatically with new Omarchy releases. To customize one, you never edit these originals; instead, you create a personal copy in ~/.config/omarchy/plugins/ that shadows the built‑in version while leaving the system tree intact.

The Cloning Workflow

The cloning process is orchestrated by bin/omarchy-plugin-clone, which coordinates with the catalog utility and shell discovery routines. The operation follows four distinct phases:

Discovery via omarchy-plugin-catalog

Before copying files, the script invokes omarchy-plugin-catalog (located at bin/omarchy-plugin-catalog) to locate the target plugin. This utility walks both the built‑in plugin tree and the user plugin tree, emitting a JSON object for each plugin containing its ID, manifest path, and source directory. This catalog serves as the single source of truth for the shell when enabling, disabling, or cloning plugins.

Copying and Path Rewriting

Once located, the copy_plugin function (lines 16‑45 of bin/omarchy-plugin-clone) creates a temporary staging directory and copies the selected plugin’s files. It then uses rg (ripgrep) combined with sed to rewrite any internal path references so they point to the new user location rather than the system directory.

Manifest Updates and ID Generation

The update_manifest function (lines 53‑80) transforms the copied manifest.json to reflect its new status. It injects three critical changes:

• A new unique ID prefixed with your UNIX username (<user>.<original-id>) so clones remain personal and never clash with other users on shared systems.
• A friendly display name formatted as “My <plugin‑name>”.
• A clonedFrom field that records the original built‑in ID, allowing the shell to route IPC calls correctly between the clone and the original.

Installation and Activation

After the temporary copy moves to its final destination (~/.config/omarchy/plugins/<user>.<plugin-id>/), the script triggers a plugin rescan via omarchy-shell shell rescanPlugins and immediately enables the clone using omarchy-plugin-enable. A desktop notification confirms the operation with the message “Original plugin has been replace by clone.” If you passed the --edit flag, the script then execs your $EDITOR on the new directory (lines 65‑68).

Practical Usage Examples

List available built‑in plugins before selecting one:

omarchy plugin list --first-party

Clone the clock plugin to your user configuration:

omarchy plugin clone omarchy.clock

Clone and immediately open for editing:

omarchy plugin clone omarchy.clock --edit

After execution, your clone resides at ~/.config/omarchy/plugins/<your-username>.clock/ with a rewritten manifest that preserves IPC compatibility through the clonedFrom field.

Key Implementation Files

• bin/omarchy-plugin-clone – Implements the cloning command, handling copy logic, manifest rewriting, rescanning, enabling, and optional editing.
• bin/omarchy-plugin-catalog – Provides the JSON catalog of all plugins used by the clone command to resolve source paths and metadata.
• shell/plugins/README – Documents the layout of first‑party plugins, the structure of manifest.json, and entry‑point conventions referenced during cloning.
• docs/omarchy-shell.md – Describes the shell architecture, plugin discovery mechanisms, and IPC routing that relies on the clonedFrom manifest field.

Summary

• Omarchy stores built‑in plugins in $OMARCHY_PATH/shell/plugins, but you must never edit these directly.
• The omarchy plugin clone command copies a plugin to ~/.config/omarchy/plugins/ with a user‑prefixed ID (<user>.<original-id>).
• The copy_plugin and update_manifest functions in bin/omarchy-plugin-clone handle path rewriting and manifest generation.
• A clonedFrom field in the new manifest ensures IPC calls route correctly to the original built‑in plugin ID.
• Use the --edit flag to open the cloned plugin immediately in your default $EDITOR.

Frequently Asked Questions

Can I modify a built‑in Omarchy plugin without cloning it?

No. Omarchy enforces a strict separation between system plugins and user customizations. The source files under $OMARCHY_PATH/shell/plugins are managed by the Omarchy installation and will be overwritten during updates. Always use omarchy plugin clone to create a personal copy in ~/.config/omarchy/plugins/ before making changes.

What happens if two users on the same machine clone the same plugin?

The cloning system prevents conflicts by prefixing the new plugin ID with the UNIX username (e.g., alice.omarchy.clock vs. bob.omarchy.clock). Because each clone receives a unique identifier based on the current user, multiple users can maintain independent copies of the same built‑in plugin without interference.

How does Omarchy know which original plugin my clone extends?

The update_manifest function injects a clonedFrom field into the new manifest.json that stores the original built‑in plugin ID. According to the Omarchy shell architecture documented in docs/omarchy-shell.md, this field allows the IPC system to route calls back to the original plugin ID while your clone overrides the visible behavior.

Does cloning a plugin automatically disable the original built‑in version?

Yes. After omarchy-plugin-clone finishes copying files and updating the manifest, it runs omarchy-plugin-enable on the new user plugin and the shell rescans the plugin tree. The cloned plugin effectively shadows the original, and the notification “Original plugin has been replace by clone” confirms that the built‑in version is no longer active for your session.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}