How the source: git-subdir Shape Works for Claude Plugin Entries

The source: git-subdir shape allows multiple plugins to coexist in a single repository by declaring that a plugin's code resides in a specific subdirectory, using the subdir field to specify the path and a sha for version pinning.

The anthropics/claude-plugins-community repository uses a centralized manifest system to manage plugin distribution without requiring separate repositories for each component. When a plugin entry specifies source: git-subdir, it indicates that the plugin code lives within a subdirectory of the same repository rather than an external standalone repo. This shape enables maintainers to host multiple plugins in a monorepo structure while preserving isolated versioning and entry points for each component.

Understanding the git-subdir Shape in marketplace.json

The Central Manifest File

Each plugin is described in the .claude-plugin/marketplace.json manifest located at the repository root. This file contains an array of plugin objects where the source field determines how the plugin loader locates the code.

When source is set to git-subdir, the entry signals that the plugin files exist in a subdirectory of the current repository. The loader then interprets additional properties—specifically subdir (or path) and sha—to locate and version the plugin code.

Real-world examples appear throughout the manifest:

• Line 57: source: "git-subdir" pointing to a financial plugin
• Line 79: source: "git-subdir" for a data analysis tool
• Line 91: source: "git-subdir" referencing a utility plugin

Required Fields for git-subdir Entries

A valid git-subdir entry requires specific fields that tell the loader exactly where to find and how to execute the plugin:

Field	Description
source	Must be the exact string "git-subdir" to trigger subdirectory resolution.
subdir	Relative path from repository root to the plugin directory (e.g., tres-finance-plugin).
entrypoint	The script or executable invoked when the plugin runs (e.g., main.py or run.sh).
sha	The commit SHA for reproducibility; the loader checks out this specific version.
manifest	Optional path to a plugin-specific .claude-plugin/plugin.json containing metadata.

How the Plugin Loader Resolves git-subdir Entries

Path Resolution and Execution

When a Claude client requests a plugin, the platform reads the manifest entry and resolves the subdir path to the appropriate directory. The loader constructs the execution context by combining the subdir value with the entrypoint script.

The resolution process works as follows:

1. Parse .claude-plugin/marketplace.json to extract the plugin object
2. Verify source equals "git-subdir"
3. Read the subdir value to locate the directory (e.g., tres-finance-plugin)
4. Check out the specific sha for reproducible builds
5. Execute the entrypoint relative to the subdirectory path

A simplified Bash implementation of this resolution logic:

# Extract the plugin entry from the manifest

ENTRY=$(jq -r '.plugins[] | select(.name=="tres-finance-plugin")' .claude-plugin/marketplace.json)

# Parse resolution fields

DIR=$(echo "$ENTRY" | jq -r .subdir)        # -> "tres-finance-plugin"

SHA=$(echo "$ENTRY" | jq -r .sha)           # -> "a1b2c3d4e5f6g7h8i9j0"

ENTRYPOINT=$(echo "$ENTRY" | jq -r .entrypoint)

# The loader checks out the given SHA and runs the entrypoint relative to $DIR

cd "$DIR" && exec "./$ENTRYPOINT"

Version Pinning with SHA

Unlike external repositories that might track HEAD or tags, git-subdir entries rely on the sha field for deterministic versioning. This ensures that even as the main repository evolves, the plugin loader always checks out the exact commit specified in the manifest, providing reproducible builds and cached execution states.

Validation and CI/CD Checks

The repository includes automated validation scripts in .github/actions/validate-plugins that verify git-subdir entries before merging.

Change Detection

The script .github/actions/validate-plugins/scripts/00-detect-changes.sh scans the manifest for entries where source equals git-subdir. It identifies which subdirectories contain modified code and triggers targeted validation for those specific plugins rather than checking the entire repository.

Manifest Validation

The script .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh performs integrity checks on each git-subdir entry:

• Verifies the subdir path exists in the repository
• Confirms the subdirectory contains a valid .claude-plugin/plugin.json
• Validates that the entrypoint file exists at the specified path
• Checks that the sha references a valid commit in the repository history

These checks ensure that every git-subdir entry points to a functional, properly structured plugin before the changes reach the main branch.

Complete Configuration Example

The following JSON fragment from .claude-plugin/marketplace.json demonstrates a fully configured git-subdir entry:

{
  "name": "tres-finance-plugin",
  "source": "git-subdir",
  "subdir": "tres-finance-plugin",
  "entrypoint": "run.sh",
  "sha": "a1b2c3d4e5f6g7h8i9j0",
  "manifest": ".claude-plugin/plugin.json"
}

This structure references a directory tres-finance-plugin/ at the repository root. Inside that directory, the loader expects to find run.sh as the executable entry point and tres-finance-plugin/.claude-plugin/plugin.json as the metadata manifest.

Summary

• The source: git-subdir shape enables monorepo hosting for Claude plugins by declaring that code lives in a subdirectory rather than an external repository.
• Required fields include subdir (path), entrypoint (executable), and sha (version pin).
• The loader resolves these entries by checking out the specified SHA and executing the entrypoint within the subdirectory context.
• Validation scripts in .github/actions/validate-plugins verify that git-subdir entries point to real directories with valid .claude-plugin/plugin.json manifests.
• This approach maintains multiple plugins in a single repository while ensuring reproducible versioning through commit SHA pinning.

Frequently Asked Questions

What is the difference between git-subdir and external repository sources?

git-subdir indicates the plugin code exists within the same repository as the manifest, specifically in a subdirectory defined by the subdir field. External repository sources would specify a remote URL or different repository identifier. The git-subdir shape keeps everything in one monorepo for easier maintenance and atomic updates across multiple plugins.

Can I use path instead of subdir in the manifest?

Yes, the manifest accepts either subdir or path as the field name to specify the directory location. Both fields serve the same function: telling the loader where to find the plugin files relative to the repository root. However, subdir is the preferred and more commonly documented field name in the anthropics/claude-plugins-community repository.

How does the validation script verify git-subdir entries?

The validation script .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh reads each entry with source: "git-subdir" and performs filesystem checks. It verifies that the subdirectory exists, contains a valid .claude-plugin/plugin.json file, and that the entrypoint script is present and executable. This ensures that merged entries reference functional code rather than broken or missing paths.

Why is the sha field required for git-subdir entries?

The sha field provides deterministic versioning by pinning the plugin to a specific commit hash. Even though the code lives in the same repository, the SHA ensures that clients always load the exact version of the plugin specified in the manifest, preventing unexpected behavior when the repository HEAD advances. This supports reproducible builds and allows the platform to cache plugin versions effectively.

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