Diagnosing plugins

Diagnosing Plugin Configuration

Goal: reduce any plugin problem to a single concrete fix.

Plugins are managed in Settings → Plugin Management — the Installed tab (enable/disable, view details, configure, uninstall) and the Discover tab (browse, install, and add marketplaces via the + button).

Key facts: enable/disable state is stored under plugins in ~/.zcode/cli/config.json; the official marketplace is zcode-plugins-official; and for cloning marketplace repositories behind a proxy, ZCode reads the proxy from ZCODE_HTTP_PROXY (a bare http_proxy is not used).

1. Plugin lifecycle and persistence

• Discovery sources (first match wins): inline directories, bundled official plugins, the official plugin cache, and marketplace-installed plugins. The entire subsystem is governed by the plugins.enabled master switch.
• Manifest location (probed in order): .zcode-plugin/plugin.json (preferred), then .claude-plugin/plugin.json, then .codex-plugin/plugin.json. A plugin's identity is <name>@<marketplace>.
• Enable/disable resolution: an explicit enable/disable entry always wins; only when no entry exists does the plugin's default-enabled status apply. A disabled plugin still appears in the list as disabled, but its components resolve to nothing.
• Persistence (all under plugins in ~/.zcode/cli/config.json): the enable/disable map, per-plugin configuration values, and the list of suppressed (uninstalled) built-in plugins. Because a built-in plugin ships with the application and cannot be deleted, "uninstalling" one records a suppression marker that hides it from discovery.
• Built-in seeding: on first launch, bundled official plugins are materialized into the plugin cache and registered in the official marketplace listing. This is idempotent and only re-materializes on a content or version change.

2. Manifest schema

• plugin.json: requires name (matching ^[a-z0-9][a-z0-9._-]{0,127}$); optional version (defaults to 0.0.0), description, commands/skills/hooks/mcpServers, and userConfig.
• Recorded but not executed: agents, channels, lspServers, outputStyles, settings.
• Component paths are validated: an absolute path or one that escapes the plugin root is rejected as an invalid component path.
• userConfig: type is one of string, number, boolean, directory, or file, with title, description, default, required, and sensitive. A sensitive value cannot currently be entered in the interface or persisted to the configuration file.
• marketplace.json: { name, plugins[], pluginRoot?, allowCrossMarketplaceDependenciesOn? }. Each plugins[].source may be a relative path string or an object of kind directory, github, git, url, or git-subdir; npm and pip are not supported.

3. Managing plugins in the client

• Install: on the Discover tab, find the plugin card and click Get; when done it shows Installed. New plugins are enabled by default.
• Enable / disable: on the Installed tab, toggle the switch on the plugin's row. Disabling removes all of its components from the session immediately.
• Configure: open the plugin's detail view and expand Advanced to fill in its configuration values (required fields are marked; sensitive fields cannot be entered here).
• Uninstall: from the detail view; a built-in plugin can only be disabled, not uninstalled.
• Add a marketplace: the + button on the Discover tab accepts a GitHub repository, a Git URL, a local directory, or a file.

4. Common pitfalls (symptom → cause → fix)

1. A plugin is not listed at all — its marketplace was never added, so there is no installation record or cache; or plugins.enabled is false. → Add the marketplace on the Discover tab and install it, or set plugins.enabled: true.
2. Adding a marketplace or installing fails to clone — an error such as RPC failed, timed out, or early EOF (after retries). The clone process did not inherit the shell proxy. → Set ZCODE_HTTP_PROXY=http://host:port (ZCode reads the proxy only from this variable; a bare http_proxy is ignored).
3. Enabled but its skills or commands are missing — a component path escapes the plugin root, the plugin is actually disabled, or it is not being treated as enabled where the session reads it. → Open the plugin's detail view to see the invalid component, and make the manifest path relative and inside the plugin root.
4. A built-in plugin still appears after being disabled, or returns after uninstalling — the suppression state was not applied where it was read. → Confirm the plugin id is in the suppressed-built-ins list in ~/.zcode/cli/config.json; restoring it removes that entry and re-seeds.
5. Not enabled as expected — listed as enabled but a skill reports "not found" in the session — the default-enabled set was not applied along the session's discovery path even though the listing shows it enabled. → Verify the plugin's skills are actually available in the session (via Settings → Skills and the / menu), not only that the plugin shows as enabled.
6. Manifest parse error — the JSON is invalid, is not an object, or has a missing/invalid name. → Fix it into a valid object whose name matches the pattern.
7. Invalid plugin name — the name violates ^[a-z0-9][a-z0-9._-]{0,127}$. → Rename.
8. Unresolved or cross-marketplace dependency — a dependency lives in another marketplace not listed in allowCrossMarketplaceDependenciesOn, is missing, or forms a cycle. → Add the target marketplace to allowCrossMarketplaceDependenciesOn, install the missing dependency's marketplace, or break the cycle. Dependencies are written as name@marketplace.
9. Version shows 0.0.0 or updates are not detected — Git/URL plugins often lack a top-level version, and official plugins track updates by commit. → Confirm the installed record and the manifest entry both carry their source revision.
10. A sensitive configuration value cannot be set — the field is disabled with a note that it requires secure storage. There is no secure credential store yet. → Remove sensitive: true, or provide the value out of band (for example via an environment variable); it cannot be persisted today.
11. A filesystem/sea source reports "unsupported" — a built-in plugin's cache path is missing or stale. → Re-seed the plugin (clearing its cache entry so it is re-materialized on the next launch).

5. Localization workflow (in order)

1. Is the subsystem on? Check plugins.enabled (false means everything is empty).
2. Look at the plugin. On the Installed tab, confirm whether the plugin is present and enabled; open its detail view for its source, components, and any warnings.
3. Classify by presence. Entirely absent → a marketplace or installation problem (confirm the marketplace was added and the plugin installed). Present but disabled → check the enable state against the default. Present and enabled but broken at runtime → a component-path problem (pitfall 3) or a session-versus-listing divergence (pitfall 5).
4. Built-in issues. Compare the suppressed-built-ins list against what the official marketplace offers, and confirm the plugin cache is current.
5. Installation and network. Reproduce the clone with the proxy set, confirming ZCODE_HTTP_PROXY, and look for the retryable-error signatures.
6. Session-versus-listing divergence. If the plugin shows enabled but its capabilities are absent in the session, treat it as a discovery-path problem: confirm the plugin's skills and commands actually appear in the session (Settings → Skills, the / menu), not merely that the plugin is enabled.