[DOCS] Docs promise repo-declared plugins install in cloud sessions; CLI deliberately skips them

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/cloud-environments#what-carries-over-from-your-setup

Section/Topic

cloud code sessions and plugins

Current Documentation

Summary

Two docs pages state that declaring a plugin under enabledPlugins in a repo's
.claude/settings.json is the supported way to get a plugin into a Claude Code
cloud session. The CLI deliberately refuses to do this for any plugin whose source
is external (a GitHub marketplace), per the v2.1.195 behavior change. The result is
that there is currently no working path to use a self-published marketplace plugin in
a cloud session on a personal (non-Team/Enterprise) plan, and the docs actively point
users at the path that cannot work.

A second, likely separate defect: the headless installer reports no marketplaces
declared even though extraKnownMarketplaces is present in the project settings file
that the same startup sequence demonstrably read.

Version: 2.1.234 (Claude Code), Claude Code on the web, Anthropic-hosted cloud
environment, network access level Trusted.

Reproduce

1. Publish a plugin marketplace to a public GitHub repo — .claude-plugin/marketplace.json

with metadata.pluginRoot: "./plugins" and one entry {"name": "house-style", "source": "house-style"}.

1. In a second repo, commit .claude/settings.json:

``json
{
"extraKnownMarketplaces": {
"ericeslinger": {
"source": { "source": "github", "repo": "ericeslinger/claude-skills" }
}
},
"enabledPlugins": { "house-style@ericeslinger": true }
}
``

1. Start a Claude Code cloud session on the second repo.

Expected

The plugin installs at session start and its skills are available, per the docs quoted
below.

Actual

No marketplace is registered, no plugin is installed, and the plugin's skills never
appear. ~/.claude/plugins/installed_plugins.json stays {"version": 2, "plugins": {}}
and ~/.claude/plugins/cache is never created.

Startup log (/tmp/claude-code.log), trimmed to the relevant lines:

00:18:37.827 [DEBUG] installed_plugins.json doesn't exist, returning empty V2 object
00:18:37.838 [DEBUG] Skipping orphaned enabledPlugins entry house-style@ericeslinger:
                     marketplace not registered
00:18:38.375 [DEBUG] Creating installed_plugins.json from settings.json files
00:18:38.375 [DEBUG] Skipped auto-recording house-style@ericeslinger
                     — enabled only by repo-authored settings
00:18:38.376 [DEBUG] Saved 0 installed plugins to /root/.claude/plugins/installed_plugins.json
00:18:38.377 [DEBUG] Sync completed: 0 added, 0 updated in installed_plugins.json
00:18:38.792 [DEBUG] Watching for changes in setting files /root/.claude/settings.json,
                     /home/user/hubbub-club/.claude/settings.json, ...
00:18:38.951 [DEBUG] installPluginsForHeadless: starting
00:18:38.952 [DEBUG] installPluginsForHeadless: no marketplaces declared

The Skipped auto-recording … enabled only by repo-authored settings line is clearly
intentional and consistent with the documented v2.1.195 guard. The problem is that two
other docs pages promise the opposite.

The contradiction

https://code.claude.com/docs/en/cloud-environments#what-carries-over-from-your-setup — the "What carries over from your setup" table:

| Plugins declared in .claude/settings.json | Yes | Installed at session start from the marketplace you declared. Requires network access to reach the marketplace source |

https://code.claude.com/docs/en/desktop#install-plugins — the "Install plugins" section:

The plugin browser is not available in cloud sessions, and plugins you install from the desktop app aren't available for cloud sessions; to use a plugin in a cloud session, declare it in the repository's .claude/settings.json under enabledPlugins so it installs at session start.

https://code.claude.com/docs/en/discover-plugins#configure-team-marketplaces — "Configure team marketplaces", which states the actual behavior:

As of Claude Code v2.1.195, adding the marketplace doesn't install plugins that come from an external source, on any path that loads plugins. A plugin that only the project's .claude/settings.json enables, and that comes from an external source such as a GitHub repository or npm package, doesn't load until the team member installs it.

The cloud-environments note "Requires network access to reach the marketplace source"
implies a fetch is attempted and that network is the only failure mode. Neither is true
here: the environment is Trusted (GitHub allowlisted), and cloning the marketplace
repo from inside the same session succeeds. No fetch is attempted at all.

Second symptom: marketplace not registered either

Per "Configure team marketplaces", extraKnownMarketplaces in project settings should
still register the marketplace even when the plugin isn't auto-installed — that's what
makes the follow-up claude plugin install possible. That doesn't happen:
installPluginsForHeadless reports no marketplaces declared, while the same startup
read enabledPlugins out of that identical file (it names house-style@ericeslinger
in the orphan warning one second earlier). So the two keys in one settings file are
being honored inconsistently.

Because /plugin is unavailable in a cloud session, and the session is non-interactive,
there is no in-session way for the user to complete the install the guard defers to.

Impact

On a personal Pro/Max plan there is no remaining path:

• https://claude.ai/admin-settings/plugins (org catalog sync) is Team/Enterprise only, and

additionally requires the marketplace repo be private or internal.

• Desktop-app plugin installs explicitly don't reach cloud sessions.
• Repo .claude/settings.json is the documented route, and is guarded off.

Suggested resolution

Any one of:

1. Let cloud sessions auto-install repo-declared plugins — the repo is already trusted

enough to run its own .claude/settings.json hooks and setup scripts, so the
supply-chain argument for the guard is weaker here than on a local workstation.

1. Keep the guard but honor extraKnownMarketplaces so the marketplace registers, and

surface an actionable startup message naming the claude plugin install command to
run, instead of the silent Skipping orphaned enabledPlugins entry debug line.

1. At minimum, correct the cloud-environments table row and the desktop page so they

stop pointing users at a path that cannot work, and state the plan requirement.

Pages needing an edit

| Page | Section | What's wrong |
| :--- | :--- | :--- |
| https://code.claude.com/docs/en/cloud-environments#what-carries-over-from-your-setup | "What carries over from your setup" | The Plugins declared in .claude/settings.json row says Yes; it is No for any external-source plugin. The "Requires network access" note implies network is the only failure mode. |
| https://code.claude.com/docs/en/desktop#install-plugins | "Install plugins" | Directs cloud-session users to enabledPlugins "so it installs at session start" — it does not. |
| https://code.claude.com/docs/en/discover-plugins#configure-team-marketplaces | "Configure team marketplaces" | Correct on the guard, but doesn't say the deferred claude plugin install is unreachable in a cloud session, where /plugin does not exist. |
| https://code.claude.com/docs/en/plugin-marketplaces#plugin-sources | "Plugin sources" note | Org-settings distribution rules — worth cross-linking as the only working alternative, with its Team/Enterprise and private-repo requirements. |

What's Wrong or Missing?

Expected

The plugin installs at session start and its skills are available, per the docs quoted
below.

Actual

No marketplace is registered, no plugin is installed, and the plugin's skills never
appear. ~/.claude/plugins/installed_plugins.json stays {"version": 2, "plugins": {}}
and ~/.claude/plugins/cache is never created.

Suggested Improvement

Any one of:

1. Let cloud sessions auto-install repo-declared plugins — the repo is already trusted

enough to run its own .claude/settings.json hooks and setup scripts, so the
supply-chain argument for the guard is weaker here than on a local workstation.

1. Keep the guard but honor extraKnownMarketplaces so the marketplace registers, and

surface an actionable startup message naming the claude plugin install command to
run, instead of the silent Skipping orphaned enabledPlugins entry debug line.

1. At minimum, correct the cloud-environments table row and the desktop page so they

stop pointing users at a path that cannot work, and state the plan requirement.

Impact

High - Prevents users from using a feature

Additional Context

_No response_