# How to Clone a Built‑in Omarchy Plugin to Your User Configuration > Easily clone an Omarchy built-in plugin to your user config using omarchy plugin clone. Customize plugins without altering system files and gain full editing freedom. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-24 --- **Run `omarchy plugin clone ` 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`](https://github.com/basecamp/omarchy/blob/main/manifest.json) to reflect its new status. It injects three critical changes: - A new unique ID prefixed with your UNIX username (`.`) so clones remain personal and never clash with other users on shared systems. - A friendly display name formatted as “My ”. - 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/./`), 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: ```bash omarchy plugin list --first-party ``` Clone the clock plugin to your user configuration: ```bash omarchy plugin clone omarchy.clock ``` Clone and immediately open for editing: ```bash omarchy plugin clone omarchy.clock --edit ``` After execution, your clone resides at `~/.config/omarchy/plugins/.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`](https://github.com/basecamp/omarchy/blob/main/manifest.json), and entry‑point conventions referenced during cloning. - **[`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/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 (`.`). - 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`](https://github.com/basecamp/omarchy/blob/main/manifest.json) that stores the original built‑in plugin ID. According to the Omarchy shell architecture documented in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/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.