mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-07-23 16:36:23 +00:00

feat(docs): add /docs/plugins catalog page fed by plugin-catalog/ extractor

- website/scripts/extract-plugins.py: reads plugin-catalog/*.yaml (+removed.yaml),
  emits static/api/plugins.json + plugins-meta.json; degrades to an empty
  catalog with exit 0 when plugin-catalog/ does not exist yet
- website/src/pages/plugins/: catalog page with search, tier tabs
  (All/Official/Community), capability chips, pinned-SHA repo links,
  copyable install commands, and an empty-state submission CTA
- cross-nav between Skills Hub and Plugin Catalog pages + navbar item
- user docs: user-guide/features/plugin-catalog.md (trust model, install,
  submission checklist, custom git-URL contrast), registered in sidebars.ts
- wired into deploy-site.yml and prebuild.mjs; artifacts gitignored
- tests: tests/website/test_extract_plugins.py

2026-07-22 07:28:53 -07:00

4.9 KiB

Raw Blame History

sidebar_position	sidebar_label	title	description
13	Plugin Catalog	Plugin Catalog	Browse and install reviewed, SHA-pinned Hermes plugins from the curated catalog

Plugin Catalog

The plugin catalog is a curated, human-reviewed directory of Hermes plugins you can install by name with a single command:

hermes plugins install <name>

Browse it visually at /docs/plugins — search, tier filters (Official / Community), capability chips, and copyable install commands for every entry.

The catalog complements — it does not replace — the existing plugin system. Anything you can install from the catalog is a normal plugin under the hood; the catalog just adds discovery and a review layer on top.

What's in an entry

Each catalog entry is a small YAML file in the plugin-catalog/ directory of the hermes-agent repository, declaring:

Field	Meaning
`name`	The catalog key you pass to `hermes plugins install`
`repo`	The plugin's public git repository
`sha`	The exact 40-hex commit that was reviewed — installs check out this pin, not a branch tip
`tier`	`official` (maintained by NousResearch) or `community`
`maintainer`	Who owns the plugin
`capabilities`	Declared tools, hooks, middleware, and required env vars
`requires_hermes`	Minimum Hermes version, e.g. `>=0.19` (optional)
`platforms`	OS restrictions, empty = all (optional)
`docs_url`	External documentation link (optional)

Trust model

The catalog is designed so you know exactly what you're installing:

Human-merged admission. Every entry (and every pin update) lands via a pull request reviewed by a maintainer. Nothing enters the catalog automatically.
Exact SHA pins. Entries pin a specific commit, not a branch. A plugin author pushing new code to their repo does not change what the catalog installs — updating the pin requires another reviewed PR.
Capability declarations. Entries state up front which tools, hooks, and middleware the plugin provides and which environment variables (API keys etc.) it needs, so you can judge its blast radius before installing.
Removed list. Plugins pulled from the catalog (for example after a security incident) go on plugin-catalog/removed.yaml with a reason and date. The installer refuses to install anything on the removed list.
Installed ≠ enabled. Installing a catalog plugin puts it on disk; like any plugin it must still be enabled before it loads. See Plugins → Enabling and disabling.

:::warning Catalog review is a point-in-time review A catalog entry means the pinned commit was looked at by a human, capability declarations were checked, and the repo met the submission bar. It is not a security audit, and it says nothing about other commits in the same repository. Review the code of anything you give credentials to. :::

Installing from the catalog

# Install a reviewed catalog entry by name (checks out the pinned SHA)
hermes plugins install <name>

# Then enable it, as with any plugin
hermes plugins enable <name>

The install prompt shows the entry's capability summary — declared tools, hooks, and required env vars — before anything is cloned.

Custom git URLs are different

hermes plugins install <git-url> still works for any repository, but it bypasses the catalog entirely:

No review — you get whatever is at the branch tip, not a reviewed pin.
A warning banner is shown to make clear the code is unvetted.
The removed list is still consulted (a known-bad repo is refused by URL).

Use the git-URL path for your own plugins and repos you already trust; use the catalog for discovery.

Submitting a plugin to the catalog

Submissions are pull requests that add one plugin-catalog/<name>.yaml file. The full checklist lives in the plugin-catalog README; in short, an entry must be:

Owner-submitted — the PR author owns or maintains the plugin repo.
A public repository — the repo URL is publicly cloneable.
Released — the repo has real releases/tags, not just a default branch.
Passing validation — the catalog validation GitHub Action is green on the PR (schema, SHA format, reachability).
Pinned to settled code — the pinned SHA is at least 2 weeks old, so the catalog never points at code pushed moments before review.

Pin updates (bumping sha to a newer commit) follow the same PR + review process.

4.9 KiB Raw Blame History