hermes-agent/plugin-catalog/README.md

# Hermes Plugin Catalog

Curated, Nous-approved Hermes plugins. Each YAML file in this directory
(except `removed.yaml`) is one catalog entry, discoverable via
`hermes plugins catalog` / `hermes plugins search` and installable with
`hermes plugins install <name>`.

## Admission policy

Presence in this directory **is** the trust signal. The rules that keep it
meaningful:

<!-- admission-rules:start (mirrored in website/docs/developer-guide/plugins/catalog-submission.md; tests/website/test_catalog_rules_mirror.py keeps them identical) -->
1. **Human-merged gate.** Entries are added *only* via a PR to the
   `hermes-agent` repository, reviewed and merged by a maintainer. There is
   no self-serve registry, no automated ingestion.
2. **Exact SHA pins are mandatory.** Every entry pins a full 40-character
   commit SHA. Branches, tags, and short SHAs are rejected by the loader.
   Installs clone the repository and check out exactly that commit.
3. **No self-updating code.** A listed plugin must not fetch and replace
   its own files (in-app "check for updates", signed release downloaders,
   remote `plugin.js` loaders). The exact SHA pin *is* the trust model; a
   self-updater lets an installed copy move to a commit nobody reviewed.
   Updates reach users only through a SHA-bump PR here plus
   `hermes plugins update <name>`. Keep the updater in the standalone
   distribution if you want one; strip it from the catalog build.
4. **SHA bumps are new PRs.** Updating an entry's pin is a new PR whose diff
   (old SHA → new SHA) is re-reviewed like any other change — reviewers are
   expected to look at the upstream commit range being adopted.
5. **Owner-or-major-contributor submissions, or a maintainer-curated sweep.**
   An entry may be submitted by the plugin repository's owner or a major
   contributor to it; drive-by submissions of third-party repos are declined.
   Hermes maintainers may also add entries in batches from a reviewed sweep
   of community plugins (every pin validated and scanned at the pinned
   commit, self-updater and credential-store checks run, English-first UI).
   Authors of swept-in entries keep control: a PR from the owner adjusting
   or removing their entry is accepted on request, and SHA bumps stay
   owner-or-maintainer PRs under rule 4.
6. **Declared capabilities must match reality.** The `capabilities:` block
   (tools, hooks, middleware, env vars) must match what the plugin actually
   registers at the pinned commit. Validation fails the entry otherwise —
   undeclared capability creep is treated as a security issue.
7. **The install scanner runs at admission.** `hermes plugins validate` includes
   the `security scan` check: `dangerous` fails the entry; `caution` findings
   appear as warnings in the CI log and the reviewer reads them before merging.
   In exchange, installs at the pinned SHA accept `caution` without a prompt
   (`dangerous` still blocks). Review the warnings; do not merge past them.
8. **Desktop plugins stay inside the SDK surface.** A `desktop/plugin.js` runs
   in the Desktop renderer with the app's full authority (the loader isolates
   errors, not capabilities), so a listed one may only use the plugin SDK:
   no prototype patching (`X.prototype.y =`, `Object.defineProperty(...prototype`),
   no `eval`/`new Function`, no `import()` of anything but `@hermes/plugin-sdk`
   / `react` (app bundle chunks, blob or http URLs included), no script-tag
   injection, no reaching into the app's internal stores or its own markup
   (querying `data-slot` / `data-tour` / `data-sidebar` / `data-testid`
   elements from `document`, or a `document.body` MutationObserver, to restyle,
   hide, click or rewrite core UI). `hermes plugins validate` refuses these at
   admission (`desktop surface` check); a plugin that needs a capability the
   SDK lacks asks for an SDK hook instead of patching around it.
9. **No runtime overrides of Hermes core.** A listed plugin extends Hermes only
   through public surfaces: hooks, middleware, provider profiles and the
   other `register_*` APIs, and Desktop SDK slots and routes. It must not
   replace, wrap or rebind core functions, methods, module attributes or
   private dicts in place (`AIAgent.<method> = ...`, `setattr(server, ...)`,
   `sys.modules[...]`, writes into a core module's tables). Two plugins
   patching the same seam silently break each other, and every core release
   can break both. `hermes plugins validate` refuses these at admission (`no
   core override` check). If the hook you need does not exist, open an issue
   describing it: we would rather add the seam than list a patch.
10. **Dependency security policy is the plugin's.** Hermes's 14-day
   `exclude-newer` quarantine covers Hermes's own dependencies only; a plugin's
   `python_dependencies` / `pyproject.toml` install under the plugin's policy
   (no quarantine, still inside Hermes's core constraints). Reviewers read the
   dependency list at the pinned SHA: bare floors (`>=X` with no upper bound)
   and floors on the newest release get a request for the oldest
   API-compatible floor plus an upper bound, and authors are strongly
   recommended to run their own release quarantine (`uv --exclude-newer` in
   their CI) — see the developer guide's *Dependency security policy*. A
   recent floor alone is not grounds to hold an entry.

11. **Credentials come through Hermes, never from files.** A plugin gets
   secrets only through Hermes's routes. Its declared `requires_env` and
   `config_schema` secrets are read with `agent.secret_scope.get_secret(NAME)`,
   which honours the active profile (a bare `os.environ` read can pick up another
   profile's key under multiplexing). A subscription sign-in (Codex / ChatGPT
   today) is used only through `credentialed_provider_request` with
   `requires_auth`, so Hermes attaches the token and the plugin never holds it. A
   plugin never reads `.env` files, Hermes's `auth.json`, another tool's login (a
   vendor CLI's token file, a browser profile, a keychain) or any other
   credential store directly, and never refreshes, rotates or writes OAuth tokens
   or presents itself as another vendor's client. If Hermes has no route for a
   credential a plugin needs, ask for one in a Hermes issue or PR; the plugin
   does not work around it.
12. **Approvals and unattended runs are respected.** A plugin never routes around
   Hermes's approval system: no auto-approving, no disabling guards, and no
   spawning Hermes or shell children that inherit YOLO or non-interactive mode
   to run commands nobody approved. Anything that waits for a person (a prompt,
   an OAuth browser flow) fails cleanly or times out under cron, the messaging
   gateway and other unattended runs instead of hanging the agent.
13. **Risky behaviour is disclosed.** What a user would want to know before
   installing goes in the PR description and the plugin's README: network calls
   to third-party services, reads outside the plugin's own data, shell commands,
   long-running background processes, stored credentials. Telemetry and usage
   reporting are opt-in. Reviewers summarise these as disclosure lines on the
   entry PR; undisclosed behaviour found in review is a request for changes.
14. **Compatibility metadata is truthful.** `requires_hermes` is a SemVer floor
   (`">=0.21.5"`), never a CalVer date, and never newer than the current release
   (the loader skips the plugin otherwise). `version` matches the pinned code,
   and Python dependencies resolve under Hermes's core constraints
   (`hermes plugins validate --install-deps` is what CI runs).
15. **No skins or forks of bundled plugins.** A change to a bundled plugin is a
   PR against `hermes-agent`, not a competing listing, and vendor-lookalike skins
   are not listed under Nous branding.
16. **One listing per plugin lineage.** A fork of a listed community plugin is
   listed only when it is materially different from the original: a different
   transport or architecture, or capability the original lacks and its author
   declined or has not answered a PR for 30 days. Improvements to a listed plugin
   go upstream as a PR to its author. A fork that renames, rebrands or adds small
   changes is declined in favour of the original. A listed fork names its origin
   in its disclosure line (`Derived from <entry>`).
17. **No unscannable executable payloads.** Everything a reviewer and the
   install scanner read at the pinned commit must be source they can read. A
   plugin must not ship a compiled binary (a native executable or library of
   any OS — detected by file header, not extension: ELF, Mach-O, PE/`MZ`,
   WebAssembly), committed Python bytecode (`.pyc`/`.pyo`, including sourceless
   or hash-forged caches that run instead of the `.py` beside them), or an
   archive whose members are not themselves reviewable source. A plain-text
   source bundle (a `.tar.gz` of `.py`/`.ts`/`.md` the plugin unpacks) is read
   like any other source; a bundle hiding a binary is not. The scanner cannot
   read machine code, and a checksum committed in the same commit only proves
   the file was not changed after that commit, not where it came from. If a
   plugin genuinely needs a native component, the binary must be built by the
   plugin repository's own public GitHub Actions from source in that repository
   and carry a GitHub build attestation (`actions/attest-build-provenance`) tying
   it to that workflow and commit; the gate verifies the attestation against the
   pinned commit (`gh attestation verify --repo <owner/repo> --source-digest
   <pinned sha>`). A binary a user's own machine fetches at setup time is allowed
   only from the upstream tool's official source, pinned by checksum, and
   disclosed (rule 13) — never bundled and never from an unofficial mirror.
<!-- admission-rules:end -->

The step-by-step submission guide, with the same rules and what reviewers check,
lives at
[Submitting to the plugin catalog](https://hermes-agent.nousresearch.com/docs/developer-guide/plugins/catalog-submission).

## Entry schema

```yaml
name: example-plugin        # [a-z0-9_-]{1,64}, the catalog key
repo: https://github.com/owner/repo   # https:// only
sha: <40-hex commit sha>    # mandatory exact pin
subdir: ""                  # optional; plain relative path inside the repo
                            # ([A-Za-z0-9._/-]+ only: no '..', '.', empty
                            # segments, absolute, or backslash forms)
description: One-line description.
maintainer: OwnerName
tier: official              # official | community (default community)
category: memory            # desktop | memory | platform | web | tools | voice | automation | models | general
                            # (default desktop) — the shelf the entry sits on at /docs/plugins
requires_hermes: ">=0.19"   # optional
docs_url: ""                # optional
version: "1.4.0"            # optional human label for the sha (quote it); shown as "1.4.0 @ abcd1234"
image: ""                   # optional https image on a GitHub host, 2:1 (e.g. 1200x600), e.g.
                            # https://raw.githubusercontent.com/owner/repo/<sha>/docs/banner.png
screenshots: []             # optional, up to 6 https images on a GitHub host; gallery on /docs/plugins/<name>
readme: true                # optional, default true; the README at the PINNED SHA renders on /docs/plugins/<name>
platforms: []               # optional, e.g. [linux, macos]; empty = all
title: ""                   # optional human name on cards ("NVIDIA App"); default = name
onboarding: false           # optional; offered on the Desktop onboarding card (official entries only)
known_issues: []            # optional strings shown at the install prompt; informational, never blocks
capabilities:
  provides_tools: []
  provides_hooks: []
  provides_middleware: []
  requires_env: []
```

`version`, `image`, `screenshots` and `readme` are cosmetic: none is parsed or
used to pick what installs. The sha stays the release; bump `version` in the
same PR that bumps `sha` so the label on the card matches the code. Images must
live on `raw.githubusercontent.com`, `github.com` or `*.githubusercontent.com`
so the Desktop catalog and the docs site never fetch from third-party hosts;
pin the raw URL to the entry's commit and the picture is as immutable as the
code.

Every entry gets a page at `https://hermes-agent.nousresearch.com/docs/plugins/<name>`
and every maintainer a page at `/docs/plugins/by/<maintainer>`, both generated
from these files at docs build time. `screenshots:` fills the page's gallery;
the build fetches the README (from `subdir` if set, else the repo root) **at the
pinned sha** — GitHub and GitLab repos, on by default, `readme: false` opts out — and renders it
through an allowlist (raw HTML dropped, links and images resolved against the
pinned tree). The page therefore shows the README the reviewer read, and it
changes only when a reviewed re-pin lands.

## removed.yaml — the blocklist

When an entry is pulled from the catalog for security or policy reasons, it
is recorded in `removed.yaml` with a reason and date. The installer refuses
to install anything matching a removed entry's name or repo URL, so a
malicious plugin cannot be re-installed from a stale identifier after
removal. A plugin that lands on the list after a user installed it stops
updating, cannot be enabled and is refused at load time. Removals, like
additions, land via reviewed PRs.

Delisting is different from removal: an entry that is unmaintained, superseded, squatting a
name it is not affiliated with, or no longer meets a rule is deleted from the catalog (plain
file removal, users who already installed it are unaffected). It is welcome back once the
problem is fixed; a name squatter comes back under a distinct name. When a new rule affects
entries that are already listed, their authors get an issue on their repository explaining
the change and time to update before anything is delisted.

## Names

The catalog key and the manifest `name:` are what users search, install, and — for memory
providers — put in `memory.provider`. A `memory` / `exclusive` entry must not reuse the name of
another provider or of a well-known upstream project it is not affiliated with: two providers
registering the same `register_memory_provider` name make `memory.provider` ambiguous
(whichever loads last wins). Reviewers check the registered provider name, not just the file
name, and the affiliated project gets the bare key.