Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / plugin-catalog-and-discovery

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

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

TriggerConsequenceGuard
Live catalog fetch fails and no usable cache or checkout existsA name cannot be resolved and the install surface reports unavailableUse bounded fetches and explicit unavailable status; do not guess a source
Entry is on the removal listNew install, enable, update, or load can be blockedUnion in-tree and live removals and match both catalog names and normalized repository identity
Installed plugin has a different manifest name from its catalog entryThe UI can show a duplicate or miss the installed rowMatch by installer-owned catalog provenance before runtime names
Current Hermes or host platform does not satisfy the entryInstall or re-pin would select code that cannot run hereKeep the entry visible with an incompatibility reason and refuse the operation
New pin adds capabilities or a Desktop halfAn update could widen authority without a new user decisionCompare installed and staged surfaces and require consent before publication

Key files

FileWhy to read it
plugin-catalog/README.mdDefines catalog trust, entry meaning, default behavior, and removal policy.
hermes_cli/plugin_catalog.pyDefines catalog metadata, live refresh, cache fallback, pin precedence, and removal resolution.
hermes_cli/plugins_cmd_catalog.pyConnects catalog selection to provenance, compatibility checks, installed-state joins, and capability-aware updates.
hermes_cli/plugins_discovery.pyShows how installed manifests become runtime candidates and how removed or disabled plugins are withheld.
website/…/extract-plugins.pyShows how reviewed catalog data becomes website pages and the published client snapshot.
apps/…/catalog-data.tsShows the Desktop snapshot, normalization, loading, and retry model.
apps/…/catalog-query.tsShows catalog facets, search, sorting, and update filtering.
apps/…/plugins-tab.tsxShows how public entries are reconciled with agent and Desktop installations.
tui_gateway/methods_plugin_catalog.pyShows the backend lookup contract used by deep links and install dialogs.