Ecosystems and repository mode

Scan one plugin package or an entire marketplace-style repository across supported ecosystems.

Updated:
Applies to:
Guard 3.x
Maintained by:
HOL Guard Team
Source:
github:hashgraph-online/hol-guard
Also available:
MarkdownDocs library

plugin-scanner can work against one plugin package or auto-detect several ecosystems inside a repository root.

Supported ecosystems

Ecosystem--ecosystem valueDetected byComponents scanned
Codexcodex.codex-plugin/plugin.json, .agents/plugins/marketplace.json, marketplace.jsonmanifest, marketplace entries, skills
Claude Codeclaude.claude-plugin/plugin.json, .claude-plugin/marketplace.jsoncommands, agents, skills, hooks, MCP config
DeepSeek Harnessdeepseek-harnesspackage.json with a dsh.bundle objectdeclared bundle patch and client
Gemini CLIgeminigemini-extension.jsoncommands/**/*.toml, mcpServers, context file
Kimi Codekimikimi.plugin.json, .kimi-plugin/plugin.jsondeclared skills, agents, commands, system prompt, and MCP servers
OpenCodeopencodeopencode.json, opencode.jsonc, .opencode/ directory.opencode/commands, .opencode/plugins modules, mcp servers

plugin-scanner --list-ecosystems prints the ids the installed version supports. dsh and deepseek_harness are accepted as aliases for deepseek-harness.

Use --ecosystem auto (the default) to scan every detected package in a repository, or name one ecosystem when you only want that family:

plugin-scanner scan ./plugins-repo --ecosystem claude
plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness

The --ecosystem flag belongs to scan. The other commands work from the plugin or marketplace layout they find under the path.

Repository mode

Repository mode matters most for marketplace roots:

plugin-scanner scan . --format json
plugin-scanner lint . --format json
plugin-scanner verify . --format json
plugin-scanner doctor . --component mcp --bundle dist/doctor.zip

When the path has no .codex-plugin/plugin.json but does have a Codex marketplace file, the scanner switches to repository scope. It scans each local ./plugins/... entry and skips remote marketplace entries instead of treating the repository root as one plugin. Skipped entries, with the reason for each, appear under skippedTargets in JSON output. In the GitHub Action, keep plugin_dir: "." to get the same behavior.

Codex packaging alignment

The scanner follows current Codex packaging conventions:

  • local manifest paths use ./ prefixes, and lint --fix preserves or adds them
  • .agents/plugins/marketplace.json is the preferred marketplace location
  • root marketplace.json is still supported for compatibility
  • interface metadata validation checks declared links and assets and does not require an undocumented type field

verify never runs a stdio MCP server command. Each declared stdio server is recorded as a safety-skip case that needs manual review, and that case counts as not passed. verify --online probes HTTPS remote MCP endpoints only. See Quality suite commands for the details.

submit is single-plugin on purpose, so the emitted artifact always points at one concrete plugin package. Pointing it at a marketplace root exits with an error.

Useful discovery commands

plugin-scanner --list-ecosystems
plugin-scanner . --ecosystem auto
plugin-scanner . --ecosystem claude

Next guides