Claude Plugin Fork-and-Swap Workflow: Why Both `uninstall` and `marketplace remove` Are Required

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, 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, 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 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 (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:

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:

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:

claude plugin marketplace add <your-username>/i-have-adhd

Replace <your-username> 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:

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 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 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, 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, 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 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. 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.

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