How Plugin Renames Work in Claude: Understanding the `renames` Field in `marketplace.json`

The renames field in .claude-plugin/marketplace.json automatically maps deprecated plugin identifiers to their current equivalents, ensuring Claude Code seamlessly substitutes old IDs with new ones during plugin resolution.

The anthropics/claude-plugins-community repository implements a robust migration system for plugin identifiers using a dedicated renames configuration object. When a plugin changes its ID due to refactoring, namespace changes, or consolidation, this mechanism ensures existing Claude Code sessions continue functioning without manual intervention. Understanding how the renames field in marketplace.json operates is essential for maintaining backward compatibility across the Claude plugin ecosystem.

The Plugin Resolution Pipeline

When Claude Code loads a plugin, it follows a specific resolution cascade defined in the source manifest. The process handles identifier migration transparently through four distinct stages.

Step 1: Initial ID Lookup

Claude Code first reads .claude-plugin/marketplace.json and checks whether the requested plugin id exists in the main plugins catalog. If the identifier is found, the loader proceeds with standard initialization using the metadata defined in plugin.json.

Step 2: Rename Map Validation

If the requested ID is missing from the active plugin catalog, the loader inspects the top-level renames object. This map functions as a lookup table where keys represent deprecated identifiers and values specify the canonical replacements.

Step 3: Silent Substitution

When the loader finds a match in the renames map, it treats the corresponding value as the new canonical ID. The system imports the plugin using the new identifier without alerting the user or modifying the project configuration. This substitution occurs entirely in-memory during the resolution phase.

Step 4: Transparency Guarantees

The migration is transparent to end users. The renamed plugin behaves exactly as if the new ID had been requested originally, maintaining configuration parity and functional consistency across Claude Code sessions.

Configuring Plugin Migrations in marketplace.json

The renames object resides at the root level of .claude-plugin/marketplace.json, parallel to the plugins array. Each entry follows a simple key-value structure where historic IDs point to their modern equivalents.

{
  "renames": {
    "old-plugin-id-1": "new-plugin-id-1",
    "legacy/rename-tabs": "terminal-renamer"
  },
  "plugins": [
    {
      "id": "terminal-renamer",
      "name": "Terminal Renamer",
      "entry_point": "src/plugin.ts"
    }
  ]
}

This configuration is particularly useful when:

• Renaming for clarity: Converting cryptic internal codenames to descriptive public identifiers
• Namespace migration: Moving plugins from personal scopes to organizational repositories
• ID consolidation: Merging duplicate plugins under a unified canonical name

Automatic ID Resolution in Practice

The resolution logic operates during the plugin loading phase. When a user references a deprecated ID in their project configuration, Claude Code executes the following resolution sequence as implemented in the loading mechanism:

def load_plugin(requested_id):
    manifest = read_marketplace()
    
    # Standard lookup path

    if requested_id in manifest["plugins"]:
        return import_plugin(requested_id)
    
    # Rename resolution path

    if requested_id in manifest.get("renames", {}):
        new_id = manifest["renames"][requested_id]
        return import_plugin(new_id)
    
    raise PluginNotFoundError(requested_id)

Users can reference either the legacy or modern identifier with identical results. For example, both configurations below resolve to the same plugin instance:

{
  "plugins": [
    { "id": "legacy/rename-tabs", "config": {} }
  ]
}

{
  "plugins": [
    { "id": "terminal-renamer", "config": {} }
  ]
}

Validation and Schema Enforcement

The repository maintains data integrity through automated validation workflows. The file .github/workflows/validate-plugins.yml executes continuous integration checks that verify the renames object adheres to schema requirements.

Validation ensures that:

• All values in the renames map correspond to existing plugin IDs in the plugins array
• No circular rename chains exist (where ID A points to ID B which points back to ID A)
• Deprecated IDs do not collide with active plugin identifiers

These checks prevent runtime errors and ensure the rename mechanism remains a reliable migration pathway rather than a source of resolution conflicts.

Summary

• The renames field in .claude-plugin/marketplace.json creates a bidirectional mapping between deprecated plugin IDs and their current equivalents
• Claude Code checks the rename map only after failing to find a plugin ID in the active catalog, ensuring zero overhead for standard plugin loading
• Substitution occurs silently during resolution, requiring no manual updates to existing project configurations
• The GitHub workflow defined in .github/workflows/validate-plugins.yml enforces structural integrity by validating that all rename targets exist and that no circular dependencies are introduced

Frequently Asked Questions

What happens if a plugin ID exists in both the plugins array and the renames map?

Claude Code prioritizes the active plugin definition. The loader checks the plugins catalog first, so if an ID exists there, it loads directly without consulting the renames object. This prevents accidental shadowing of live plugins by historical entries.

Can I chain multiple renames together (e.g., ID A → ID B → ID C)?

No, the validation workflow explicitly forbids circular or chained rename dependencies. Each deprecated ID must map directly to a plugin ID that exists in the active plugins array. Chained resolution would introduce unnecessary complexity and potential infinite lookup loops.

Do I need to update my project files when a plugin is renamed?

No immediate update is required. Projects referencing the old identifier continue functioning indefinitely because Claude Code resolves the substitution automatically. However, updating to the canonical ID is recommended for clarity and ensures your configuration remains aligned with current documentation.

Where is the renames field located in the repository?

The renames object is defined at the root level of .claude-plugin/marketplace.json, alongside the plugins array. According to the anthropics/claude-plugins-community source code, this configuration file serves as the central manifest for plugin discovery and migration management.

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