# Claude Plugin Fork-and-Swap Workflow: Why Both `uninstall` and `marketplace remove` Are Required > Understand why claude plugin uninstall and marketplace remove are both essential for the fork-and-swap workflow. Prevent name collisions and ensure proper plugin management. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: internals - Published: 2026-09-10 --- **Both commands are mandatory because `claude plugin uninstall` removes the upstream binary from your local runtime while `claude plugin marketplace remove` deletes the registry entry, preventing name collisions when you add a forked version of the `i-have-adhd` plugin.** When customizing the `ayghri/i-have-adhd` Claude plugin, developers must follow a specific fork-and-swap workflow to replace the upstream version with their own copy. Because both the original and the fork share the identical plugin name (`i-have-adhd`) defined in [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json), simply installing your version can cause the runtime to load the wrong binary. The Claude plugin system maintains separate layers for installed binaries and marketplace registry entries, requiring distinct cleanup commands to ensure a clean replacement. ## The Name Collision Problem in Forked Plugins The `i-have-adhd` plugin is identified by the name field in [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json), which remains `i-have-adhd` regardless of which GitHub repository hosts the code. When you fork `ayghri/i-have-adhd` to customize behavior, your repository contains the same plugin identifier as the upstream source. Claude Code checks the local plugin registry (the "marketplace") during startup to resolve names to source repositories. If the upstream entry persists, the runtime encounters a **name collision** and may prioritize or default to the original version instead of your forked copy. ## How the Claude Plugin Registry Works The Claude plugin architecture separates the concept of installation from registration. This two-layer system is why a single removal command cannot fully disassociate the upstream plugin. ### Installed Binaries vs. Marketplace Entries **Installed binaries** are the compiled or fetched plugin files that the Claude runtime executes immediately. The `claude plugin uninstall` command targets this layer, deleting the upstream code from your local plugin directory to ensure no original code executes during runtime. **Marketplace entries** are registry records stored in [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) that map plugin names to their source repositories. The `claude plugin marketplace remove` command targets this layer, eliminating the reference that would otherwise cause the runtime to automatically reinstall the upstream version on the next initialization. ## Step-by-Step Fork-and-Swap Workflow According to the repository's [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md) (lines 84-91), you must execute these commands in sequence to safely swap the upstream plugin for your fork: ### 1. Remove the Upstream Binary with `uninstall` First, eliminate the executing copy of the original plugin: ```bash claude plugin uninstall i-have-adhd ``` This command clears the **installed copy** from the runtime's plugin directory, ensuring that no code from `ayghri/i-have-adhd` remains active in your session. ### 2. Clear the Registry with `marketplace remove` Second, delete the marketplace entry that still references the upstream source: ```bash claude plugin marketplace remove i-have-adhd ``` This step is critical because the marketplace registry persists independently of installed binaries. Without this command, Claude would retain a pointer to `ayghri/i-have-adhd` and potentially reinstall the upstream version during the next plugin sync. ### 3. Add Your Fork to the Marketplace Once both the binary and registry entry are cleared, register your forked repository: ```bash claude plugin marketplace add /i-have-adhd ``` Replace `` with your GitHub handle. This command creates a new registry entry pointing to your fork rather than the upstream source. ### 4. Install the Forked Version Finally, install the plugin from your newly registered source: ```bash claude plugin install i-have-adhd@i-have-adhd ``` Because the upstream marketplace entry no longer exists, Claude resolves the `i-have-adhd` name exclusively to your forked repository. ## Why Both Commands Are Mandatory Omitting either command leaves a remnant of the upstream plugin that can interfere with your fork. If you only run `uninstall`, the marketplace entry in [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) continues referencing `ayghri/i-have-adhd`, causing the runtime to automatically reinstall the original plugin on restart. Conversely, running only `marketplace remove` leaves the binary in place, meaning the upstream code continues executing even though the registry entry is gone. Only by executing both commands do you achieve a clean state where your fork is the sole version bound to the `i-have-adhd` identifier. ## Summary - **Name collisions occur** because forks retain the same `name` field (`i-have-adhd`) defined in [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) as the upstream source. - **`claude plugin uninstall`** removes the active binary from the local runtime directory, stopping execution of upstream code immediately. - **`claude plugin marketplace remove`** deletes the registry reference in [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json), preventing automatic reinstallation of the upstream version. - **Both steps are required** before adding your fork with `claude plugin marketplace add` and installing it, ensuring Claude loads only your customized version. ## Frequently Asked Questions ### Why can't I just overwrite the upstream plugin with my fork? The Claude plugin system does not support overwriting existing marketplace entries through installation alone. Because the registry maps names to source repositories, you must explicitly remove the upstream entry with `claude plugin marketplace remove` before the system will accept a new source URL for the same plugin name. Attempting to add your fork while the upstream entry persists results in a conflict where the runtime cannot determine which repository to trust for the `i-have-adhd` identifier. ### What happens if I only run `uninstall` without `marketplace remove`? If you only execute `claude plugin uninstall i-have-adhd`, the upstream binary is deleted from your local runtime, but the marketplace registry entry remains intact. According to the workflow documented in [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md), this causes the runtime to automatically reinstall `ayghri/i-have-adhd` from the preserved registry reference during the next startup or plugin update cycle, effectively reverting your environment to the upstream version. ### Where is the plugin name defined that causes this collision? The name `i-have-adhd` is defined in the [`.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) file within the repository root. This metadata file contains a `name` field that serves as the canonical identifier for the plugin across all forks. Because GitHub forks copy this file exactly, every derivative repository shares the same identifier, necessitating the two-step removal process to prevent the runtime from confusing upstream and forked sources. ### Is the fork-and-swap workflow required for every Claude plugin customization? Yes, any time you fork a Claude plugin to modify its behavior, you must follow this workflow if the plugin name remains unchanged in [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json). The separation between binary installation and marketplace registration is a core architectural feature of the Claude plugin system, making both `uninstall` and `marketplace remove` essential steps for any fork-and-swap deployment.