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

> Understand how plugin renames work in Claude using the marketplace.json renames field. Claude Code automatically maps old plugin IDs to new ones for seamless resolution.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-12

---

**The `renames` field in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)

The `renames` object resides at the root level of [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.

```json
{
  "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:

```python
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:

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

```

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.