gemini-cli - 💡(How to fix) Fix Support installing extensions from a Git repository subdirectory [1 participants]

What would you like to be added?

Please add a supported way for gemini extensions install <repo> to install an extension that is not located at the Git repository root.

This is primarily a monorepo / multi-plugin repo problem. Today gemini extensions install <source> treats the install source root as the extension root and then looks for gemini-extension.json there. The manifest itself does not have a field that can say "the actual extension package lives at this relative path." That assumption works for one-extension-per-repo projects, but it does not work for repositories that already have another plugin marketplace layout or multiple installable packages.

There are three compatible ways this could be solved. Any one of them would unblock our use case.

Option A: Git subdirectory install primitive

Support treating a subdirectory as the extension root:

gemini extensions install https://github.com/EveryInc/compound-engineering-plugin \
  --ref main \
  --subdir plugins/compound-engineering/dist/gemini-extension

The exact flag name is not important. --subdir, --source-path, or another documented syntax would work.

Expected behavior:

1. Clone/fetch the repository at the requested ref.
2. Treat the subdirectory as the extension source root.
3. Validate <subdirectory>/gemini-extension.json.
4. Copy only the subdirectory contents into ~/.gemini/extensions/<extension-name>.
5. Persist source metadata in .gemini-extension-install.json, including source, ref, and subdirectory.
6. On gemini extensions update, re-fetch the same source/ref/subdirectory and update from that subdirectory.

This is the smallest generic primitive.

Option B: repo-level Gemini pointer manifest

Support a Gemini-specific repo-level manifest under .gemini/ that points to the actual extension root. This would be similar in spirit to how Claude Code plugin repositories can keep marketplace metadata separate from plugin package roots.

For example, a repository could contain:

<repo-root>/.gemini/gemini-extension.json
<repo-root>/plugins/compound-engineering/dist/gemini-extension/gemini-extension.json
<repo-root>/plugins/compound-engineering/dist/gemini-extension/skills/...
<repo-root>/plugins/compound-engineering/dist/gemini-extension/agents/...

The repo-level .gemini/gemini-extension.json would be a pointer/installer manifest, not necessarily the installed extension manifest itself. For example:

{
  "schemaVersion": 1,
  "extensions": [
    {
      "name": "compound-engineering",
      "path": "plugins/compound-engineering/dist/gemini-extension"
    }
  ]
}

Then users could install by repository URL and extension name:

gemini extensions install https://github.com/EveryInc/compound-engineering-plugin \
  --extension compound-engineering

Or, if there is only one extension listed, Gemini could install it by default.

This shape would be especially useful for repositories that want first-class Gemini support without making the entire repository root be a Gemini extension root.

Option C: install-time Claude Code plugin import

For repositories that already publish Claude Code plugin metadata, Gemini could add an install-time adapter/import mode. This would not require Gemini to load Claude files at runtime. Instead, Gemini would convert the source package into a native Gemini extension during install/update.

Example:

gemini extensions install https://github.com/EveryInc/compound-engineering-plugin \
  --from claude-code \
  --plugin compound-engineering

or an equivalent explicit form:

gemini extensions install https://github.com/EveryInc/compound-engineering-plugin \
  --manifest .claude-plugin/marketplace.json \
  --plugin compound-engineering

Expected behavior:

1. Clone/fetch the repository.
2. Read .claude-plugin/marketplace.json if present.
3. Resolve the requested plugin name to its plugin root, such as plugins/compound-engineering/.
4. Read that plugin's .claude-plugin/plugin.json.
5. Generate/install a native Gemini extension under ~/.gemini/extensions/<name>.
6. Store source metadata so gemini extensions update <name> can repeat the same import.

The adapter would generate Gemini's native shape:

gemini-extension.json
skills/<skill>/SKILL.md
agents/<agent>.md
GEMINI.md, if needed

The conversion step can normalize ecosystem differences, for example:

• flatten nested Claude agent directories into direct Gemini agents/*.md
• strip or map Claude-only agent frontmatter fields
• map Claude tool names to Gemini tool names where safe
• preserve portable skill directories
• handle MCP/settings only when compatible

This is the best developer experience for existing Claude-compatible plugin repos, while still keeping Gemini runtime behavior native.

Why is this needed?

Some extension authors maintain plugins in a monorepo or multi-plugin repository rather than a dedicated one-extension-per-repo layout. The core limitation is not that gemini-extension.json is impossible to find; it is that there is no supported metadata shape that lets a repo-level Gemini manifest point to the actual extension package root. Without one of the supported shapes above, users cannot install a valid Gemini extension package that lives under a subdirectory.

Our concrete use case is the Compound Engineering plugin repository:

• Repository: https://github.com/EveryInc/compound-engineering-plugin
• Current plugin source: plugins/compound-engineering/
• Desired Gemini package output: a generated Gemini extension root under a subdirectory, with gemini-extension.json, skills/, agents/, and related files

Without this support, our options are all heavier than necessary:

• create and maintain a separate Gemini-only repository
• publish release archives whose root is the generated Gemini extension
• maintain a distribution branch whose root is the generated Gemini extension
• keep a custom installer that writes directly into ~/.gemini

Gemini already has a native extension install flow, so it would be better for users if they could install from the canonical repository with one command.

Prior art / related issues

This is closely related to #7808. That issue requested both --ref and path support for Git-installed extensions. From the comments there, --ref support landed, but sub-path support did not and the issue was later closed as stale.

This request is specifically for the remaining repository-layout problem.

Related work:

• #7808: Allow specifying a ref and path for Git-installed extensions
• #17505: Bridge ecosystems by importing external plugin bundles, starting with Claude Code
• #19969: Allow extension manifests to customize standard folder names
• #23601: Open Plugin manifest support

Acceptance criteria

At least one of these paths is supported and documented:

• gemini extensions install <git-url> --ref <ref> --subdir <path> installs an extension whose gemini-extension.json lives under <path>.
• gemini extensions install <git-url> --extension <name> can use a repo-level .gemini/... manifest to find the extension root.
• gemini extensions install <git-url> --from claude-code --plugin <name> can convert a Claude Code plugin package into a native Gemini extension during install.

For the chosen path:

• Installation fails clearly if the resolved extension root does not exist or does not contain gemini-extension.json.
• The installed extension root contains the resolved extension contents, not the full repository tree.
• gemini extensions update <name> preserves and uses the stored source metadata.
• Documentation includes a monorepo example.

Additional context

This would let projects keep one canonical repository while still offering native Gemini extension install, rather than requiring a separate repo or custom installer purely because of repository layout.