Plugin catalog and discovery
The plugin catalog is Hermes's reviewed directory of installable plugins. It gives users a trusted name, a fixed source revision, useful capability and compatibility information, and a common way to find and compare plugins before installation. See Plugin platform for the wider plugin model and Plugin lifecycle and integration for installation and runtime behavior.
Catalog identity
Reviewed entries
The catalog is a curated admission list, not an open registry. Each entry identifies a public repository and an exact commit that maintainers reviewed. A pull request adds an entry or changes its pin, so the catalog revision is the boundary between a reviewed plugin and an arbitrary repository state. plugin-catalog/README.md• L8-47
The catalog also records entries that must no longer be offered. A removed name or repository remains blocked even when an installed Hermes uses an older catalog snapshot. This prevents stale discovery data from restoring a withdrawn plugin. plugin-catalog/README.md• L252-260, hermes_cli/plugin_catalog.py• L298-339
References: plugin-catalog/README.md• L8-47 plugin-catalog/README.md• L252-260 hermes_cli/plugin_catalog.py• L298-339
Entry metadata
Entry metadata connects a plugin's reviewed source to the ways Hermes presents and checks it. Identity fields select the repository, commit, and optional repository subdirectory. Human-facing fields describe the plugin and its maintainer. Classification fields place it in a browse category and trust tier.
The remaining fields describe whether the entry fits the current Hermes and host. They include the minimum Hermes version, supported platforms, declared tools, hooks, middleware, and required environment values. Presentation fields such as a title, version label, image, screenshots, documentation link, and README control the catalog view without changing what commit Hermes installs. hermes_cli/plugin_catalog.py• L98-140, plugin-catalog/README.md• L185-217
References: hermes_cli/plugin_catalog.py• L98-140 plugin-catalog/README.md• L185-217
Trust tiers
Trust tiers tell the user who stands behind an entry. official identifies Nous-maintained plugins, verified identifies plugins checked as coming from the relevant reputable vendor, and community covers other accepted entries. The tier is a review signal, not a runtime capability grant.
Only official and verified entries can be marked for default installation or onboarding. This limits broad or automatic distribution to entries with the required level of product ownership or vendor review. hermes_cli/plugin_catalog.py• L33-38, plugin-catalog/README.md• L219-233
References: hermes_cli/plugin_catalog.py• L33-38 plugin-catalog/README.md• L219-233
Catalog availability
Published catalog snapshots
Hermes reads the catalog from the checkout and from a published JSON snapshot. The documentation build publishes the same catalog data that powers the website, so an installed Hermes can learn about new entries and removals without a full Hermes update. The client uses a valid cached snapshot when possible, then falls back to the catalog shipped with the checkout.
The live snapshot is treated as a bounded and trusted source. Hermes accepts only the published HTTPS hosts and limits redirects and response size. When the live snapshot and checkout contain different pins, the newer catalog source supplies the entry so a recent checkout does not reinstall an older reviewed pin from cache. hermes_cli/plugin_catalog.py• L9-14, hermes_cli/plugin_catalog.py• L387-402, hermes_cli/plugin_catalog.py• L434-465, hermes_cli/plugin_catalog.py• L546-577
References: hermes_cli/plugin_catalog.py• L9-14 hermes_cli/plugin_catalog.py• L387-402 hermes_cli/plugin_catalog.py• L434-465 hermes_cli/plugin_catalog.py• L546-577
Availability rules
An entry is discoverable when it is present in the resolved catalog and is not on the removal list. Installation by catalog name also checks the host platform and the running Hermes version. An incompatible entry can remain visible for explanation, but Hermes refuses the install or holds a catalog update until the environment is suitable. hermes_cli/plugins_cmd_catalog.py• L282-317
Default installation and onboarding are narrower than ordinary discovery. A default entry must use an official or verified tier, and automatic fetching remains subject to the user's lazy-install security policy. A plugin can therefore be visible, selectable, and installable without being fetched automatically. plugin-catalog/README.md• L226-233, hermes_cli/default_plugins.py• L1-50
References: hermes_cli/plugins_cmd_catalog.py• L282-317 plugin-catalog/README.md• L226-233 hermes_cli/default_plugins.py• L1-50
Custom sources
Hermes separates catalog selection from custom source installation. A bare catalog name must resolve to a current catalog entry. A Git URL or repository shorthand follows the custom-source path instead and does not claim catalog review, although the removal list still applies. This keeps a reviewed name from becoming an accidental alias for unreviewed code. hermes_cli/plugins_cmd_catalog.py• L34-65, website/…/plugin-catalog.md• L217-249
References: hermes_cli/plugins_cmd_catalog.py• L34-65 website/…/plugin-catalog.md• L217-249
Catalog discovery
Browse and search
The CLI exposes the catalog as a browse and search surface. It searches names, descriptions, and declared tools, then presents category, tier, pin, and capability summaries. The Desktop application consumes a published snapshot and turns the same metadata into searchable cards, categories, source facets, tags, related entries, and detail views. hermes_cli/plugins_cmd_catalog.py• L790-837, apps/…/catalog-data.ts• L126-209, apps/…/catalog-query.ts• L19-105
The Desktop browser treats catalog data as a snapshot rather than a set of per-entry requests. It limits stalled downloads and leaves a failed load available for explicit retry. This keeps a large catalog usable while making an unavailable source visible instead of silently showing incomplete results. apps/…/catalog-data.ts• L211-301
References: hermes_cli/plugins_cmd_catalog.py• L790-837 apps/…/catalog-data.ts• L126-209 apps/…/catalog-data.ts• L211-301 apps/…/catalog-query.ts• L19-105
Catalog lookup
Deep links and install dialogs use a backend lookup for a catalog name. The lookup applies the same name validation, live-cache ladder, in-tree fallback, and removal checks as catalog installation. It returns only enough source metadata to identify the reviewed install, and it reports invalid, unknown, or unavailable states rather than guessing a repository.
This backend boundary also avoids making the renderer depend on a documentation-site redirect or cross-origin behavior. The selected name therefore reaches the same catalog resolver that will supply the install pin. tui_gateway/methods_plugin_catalog.py• L1-41, tests/…/test_plugins_catalog_lookup.py• L32-60
References: tui_gateway/methods_plugin_catalog.py• L1-41 tests/…/test_plugins_catalog_lookup.py• L32-60
Catalog presentation
The website converts each catalog file into plugin pages, author pages, browse data, and the live client snapshot during one build. It keeps the reviewed commit attached to the displayed documentation and media, so a page does not silently describe a newer branch state than the install path. website/…/extract-plugins.py• L1-23, website/…/extract-plugins.py• L95-129
The Desktop capabilities area presents plugins with the shared catalog browser used by skills. For plugins, the source facet means trust tier. The browser can show public entries beside installed entries and can filter to installed or updateable entries. apps/…/catalog-query.ts• L19-26, apps/…/catalog-query.ts• L58-105
References: website/…/extract-plugins.py• L1-23 website/…/extract-plugins.py• L95-129 apps/…/catalog-query.ts• L19-26 apps/…/catalog-query.ts• L58-105
Installed catalog state
Selection and installation
Selecting a catalog entry passes its repository, subdirectory, reviewed pin, and tier to the install flow. The install records the source revision that was actually checked out and may then enable the plugin. Installation and activation remain separate states: code can be present on disk while the plugin is not active.
The catalog name and the plugin manifest name can differ. Hermes keeps the catalog identity in installer-owned provenance rather than trusting a file inside the plugin tree. This lets later commands resolve the user's selected catalog entry even when the installed package uses another runtime name. hermes_cli/plugins_cmd_catalog.py• L67-89, hermes_cli/plugins_cmd_catalog.py• L157-203, hermes_cli/plugins_discovery.py• L320-333
References: hermes_cli/plugins_cmd_catalog.py• L67-89 hermes_cli/plugins_cmd_catalog.py• L157-203 hermes_cli/plugins_discovery.py• L320-333
Installed-state reconciliation
The dashboard and Desktop join two views of one plugin: the public catalog entry and the locally discovered installation. The join uses recorded catalog identity first and the runtime name only as a fallback. The result can show whether the entry is installed, its installed revision, its current runtime status, and whether the installed revision differs from the current catalog pin.
Desktop also joins an agent half with an app-level Desktop half when both belong to one package. Agent state follows the selected profile, while the Desktop half is shared by the application. The catalog row can therefore represent one product choice while its controls act on two different scopes. hermes_cli/plugins_cmd_catalog.py• L924-950, hermes_cli/…/dashboard_ui.py• L161-180, apps/…/plugins-tab.tsx• L653-695, apps/…/plugins-tab.tsx• L756-783
References: hermes_cli/plugins_cmd_catalog.py• L924-950 hermes_cli/…/dashboard_ui.py• L161-180 apps/…/plugins-tab.tsx• L653-695 apps/…/plugins-tab.tsx• L756-783
Capability reconciliation
Catalog capabilities are an advance description of the plugin's expected surface. Hermes compares that description with the installed manifest and its discovered runtime state. A declaration informs review and consent; it does not grant access by itself. Runtime capability consent and enablement decide what the installed plugin can use.
When a catalog pin changes, Hermes checks whether the new revision widens the plugin's tools, hooks, middleware, host capabilities, dependencies, authentication needs, or Desktop surface. A widening update requires a new user decision before publication. This keeps catalog metadata, installed code, and granted capability state aligned across updates. hermes_cli/plugins_cmd_catalog.py• L565-629, hermes_cli/plugins_cmd_catalog.py• L632-687, hermes_cli/plugins_manifest.py• L388-402
References: hermes_cli/plugins_cmd_catalog.py• L565-629 hermes_cli/plugins_cmd_catalog.py• L632-687 hermes_cli/plugins_manifest.py• L388-402
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the catalog entry schema aligned across the in-tree loader, admission validator, website snapshot, and Desktop parser.
- Keep the catalog name, recorded provenance, manifest name, and installed-state join aligned when a package uses different identities.
- Keep live-feed fallback, checkout freshness, and removal-list union behavior aligned so cache age cannot restore an old pin or withdrawn entry.
- Keep catalog capability declarations aligned with manifest probing and update consent when a new pin adds a runtime surface.
- Keep agent profile scope separate from app-level Desktop scope when changing installed package presentation or controls.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Live catalog fetch fails and no usable cache or checkout exists | A name cannot be resolved and the install surface reports unavailable | Use bounded fetches and explicit unavailable status; do not guess a source |
| Entry is on the removal list | New install, enable, update, or load can be blocked | Union in-tree and live removals and match both catalog names and normalized repository identity |
| Installed plugin has a different manifest name from its catalog entry | The UI can show a duplicate or miss the installed row | Match by installer-owned catalog provenance before runtime names |
| Current Hermes or host platform does not satisfy the entry | Install or re-pin would select code that cannot run here | Keep the entry visible with an incompatibility reason and refuse the operation |
| New pin adds capabilities or a Desktop half | An update could widen authority without a new user decision | Compare installed and staged surfaces and require consent before publication |
Key files
| File | Why to read it |
|---|---|
| plugin-catalog/README.md | Defines catalog trust, entry meaning, default behavior, and removal policy. |
| hermes_cli/plugin_catalog.py | Defines catalog metadata, live refresh, cache fallback, pin precedence, and removal resolution. |
| hermes_cli/plugins_cmd_catalog.py | Connects catalog selection to provenance, compatibility checks, installed-state joins, and capability-aware updates. |
| hermes_cli/plugins_discovery.py | Shows how installed manifests become runtime candidates and how removed or disabled plugins are withheld. |
| website/…/extract-plugins.py | Shows how reviewed catalog data becomes website pages and the published client snapshot. |
| apps/…/catalog-data.ts | Shows the Desktop snapshot, normalization, loading, and retry model. |
| apps/…/catalog-query.ts | Shows catalog facets, search, sorting, and update filtering. |
| apps/…/plugins-tab.tsx | Shows how public entries are reconciled with agent and Desktop installations. |
| tui_gateway/methods_plugin_catalog.py | Shows the backend lookup contract used by deep links and install dialogs. |