# Understanding marketplace.json Renames and Source Types in Claude Code

> Explore marketplace.json in Claude Code discover plugin renames and source types like URL or subdirectory. Learn how this manifest drives plugin discovery.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-13

---

**The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) manifest in the `anthropics/claude-plugins-community` repository drives plugin discovery through three core sections: a `renames` map for backward compatibility, a `plugins` array for metadata, and `source` objects that declare whether to fetch code via direct URL or subdirectory extraction.**

The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file serves as the single source of truth for the Claude Code community plugin ecosystem. Located at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) in the repository root, this JSON manifest dictates how the marketplace resolver locates, validates, and installs community-contributed plugins while maintaining strict reproducibility and backward compatibility.

## The Structure of marketplace.json

The manifest organizes plugin metadata into three distinct sections that work together to resolve installation requests.

### The Renames Map (Backward Compatibility)

The `renames` object at the top of the file provides transparent aliases for plugins that have changed identifiers. When a user references an outdated plugin name, the resolver consults lines 6–11 of [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) to map legacy names to current canonical identifiers.

For example, requesting `qodo-skills` automatically resolves to `qodo` because the renames map contains that specific alias definition. This prevents breaking existing workflows when maintainers reorganize plugin naming conventions.

### The Plugins Array

The `plugins` array contains structured metadata for every available community plugin. Each entry includes the plugin name, description, author information, and critically, a nested `source` object that instructs the resolver exactly how to retrieve the code.

### Source Objects: url vs git-subdir

Every plugin entry contains a `source` object with a `source.type` field that must be either `"url"` or `"git-subdir"`. These types determine the fetch strategy:

- **`url`** – Indicates the plugin resides at the root of a dedicated Git repository. The manifest provides the clone URL and a fixed SHA for reproducible installation.
- **`git-subdir`** – Indicates the plugin lives within a subdirectory of a larger repository, enabling monorepo architectures where multiple plugins share a single codebase.

## How the Resolver Processes Plugin Requests

The marketplace resolver follows a strict three-phase pipeline when handling installation commands like `claude plugin marketplace add <name>`.

First, during **Name Lookup**, the resolver checks if the requested identifier exists in the `plugins` array. If not found, it queries the `renames` object at lines 6–8 to check for legacy aliases. For instance, `qodo-skills` maps to `qodo` before the search proceeds.

Second, in **Plugin Entry Retrieval**, the resolver locates the matching entry in the `plugins` array and extracts the nested `source` configuration.

Third, during **Source Resolution**, the `source.type` value triggers specific fetch logic. For `url` sources like the `0x` plugin (defined at lines 16–20), the resolver executes `git clone` directly on the repository URL and checks out the exact SHA (`0167bbb411cc972b966127d23c23de801061fa99`). For `git-subdir` sources like `a11y-fixer` (lines 78–84), the resolver clones the parent repository, checks out the specified reference, then extracts only the subdirectory defined in the `path` field.

## Source Type Deep Dive

Each source type serves distinct repository architectures while maintaining immutable installation guarantees.

### URL Source (Root-Level Repositories)

The `url` source type supports standalone plugin repositories. The manifest entry specifies:

```json
{
  "source": {
    "source": "url",
    "url": "https://github.com/0xProject/0x-ai.git",
    "sha": "0167bbb411cc972b966127d23c23de801061fa99"
  }
}

```

This configuration guarantees that every installation pulls the exact commit `0167bbb411cc972b966127d23c23de801061fa99`, preventing supply-chain attacks from upstream repository changes.

### Git-Subdir Source (Monorepo Support)

The `git-subdir` type enables granular extraction from shared repositories:

```json
{
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/barnburner121/claude-plugin-marketplace.git",
    "ref": "main",
    "sha": "abc123...",
    "path": "generated-plugins/a11y-fixer"
  }
}

```

As implemented in the `a11y-fixer` entry at lines 78–84, this structure allows the marketplace to host multiple plugins within a single repository while installing only the relevant subdirectory.

## Security and Reproducibility Benefits

Pinning each plugin to a specific SHA prevents "moving target" vulnerabilities where malicious code could replace legitimate plugin versions. The `renames` map further ensures stability by allowing maintainers to restructure plugin identifiers without breaking existing user configurations that reference legacy names.

## Practical Implementation Examples

The following JavaScript demonstrates how to programmatically resolve a plugin using the marketplace manifest structure:

```javascript
// Resolve a plugin request using the marketplace manifest
async function resolvePlugin(name) {
  const manifest = await fetch(
    "https://raw.githubusercontent.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json"
  ).then(r => r.json());

  // Apply renames if needed
  const canonicalName = manifest.renames?.[name] ?? name;

  const entry = manifest.plugins.find(p => p.name === canonicalName);
  if (!entry) throw new Error(`Plugin ${name} not found`);

  const src = entry.source;
  if (src.source === "url") {
    // Clone repo at src.url and checkout src.sha
    return `git clone ${src.url} && git checkout ${src.sha}`;
  } else if (src.source === "git-subdir") {
    // Clone repo, checkout src.ref, then use src.path
    return `git clone ${src.url} && git checkout ${src.ref} && cd ${src.path}`;
  }
}

```

Command-line installation examples illustrate the underlying resolver behavior:

```bash

# Installing the `a11y-fixer` plugin (git-subdir source)

$ claude plugin marketplace add a11y-fixer

# Internally the resolver runs (simplified):

git clone https://github.com/barnburner121/claude-plugin-marketplace.git
git checkout main
cd generated-plugins/a11y-fixer

```

```bash

# Installing the `0x` plugin (url source)

$ claude plugin marketplace add 0x

# Internally the resolver runs:

git clone https://github.com/0xProject/0x-ai.git
git checkout 0167bbb411cc972b966127d23c23de801061fa99

```

## Summary

- **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** serves as the central manifest at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) in the `anthropics/claude-plugins-community` repository.
- The **`renames`** map at lines 6–11 provides backward-compatible aliases (e.g., `qodo-skills` → `qodo`) to prevent workflow breakage.
- **`source.type`** values (`url` or `git-subdir`) determine whether the resolver clones a standalone repository or extracts a subdirectory from a monorepo.
- SHA pinning in source configurations guarantees reproducible builds and protects against supply-chain attacks.
- The [`owner-baseline.json`](https://github.com/anthropics/claude-plugins-community/blob/main/owner-baseline.json) file tracks GitHub account IDs for repository owners to support marketplace maintenance workflows.

## Frequently Asked Questions

### What happens if I request a plugin by its old name after it has been renamed?

The marketplace resolver automatically checks the `renames` object in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) before searching the `plugins` array. If your requested name matches a key in the renames map (such as `qodo-skills` mapping to `qodo`), the resolver transparently substitutes the canonical name and proceeds with installation. This ensures backward compatibility without requiring users to update their scripts or configurations.

### How does the git-subdir source type differ from the url source type?

The `url` source type expects the plugin to exist at the root of its own Git repository, cloning the entire repo and checking out a specific SHA. The `git-subdir` type supports monorepos by cloning the parent repository, checking out a reference branch or tag, then extracting only the specified subdirectory path. This allows multiple plugins to coexist in a single repository while maintaining independent versioning through SHA pinning.

### Why does marketplace.json use SHA pinning instead of branch references?

SHA pinning guarantees immutable installations by referencing exact commit hashes rather than moving branch pointers. This prevents supply-chain attacks where a compromised repository could inject malicious code into what appears to be a stable release. Both `url` and `git-subdir` source types require a `sha` field to ensure that every installation of a specific plugin version retrieves identical code, regardless of when the installation occurs.

### Where does the marketplace store information about plugin repository owners?

Repository ownership metadata is tracked in [`.github/owner-baseline.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/owner-baseline.json), which maps GitHub account IDs to repository owners. This file supports the marketplace maintenance workflows by providing a baseline for verifying repository ownership changes and ensuring that only authorized maintainers can update plugin entries in the community marketplace.