61 plugins admitted in 65 minutes: what a catalog batch sweep actually checks

You wrote a Hermes plugin, it works well, and you want other people to install it with one command. So you read the docs, find “open a PR that adds a plugin-catalog/<name>.yaml”, and land on the repository’s pull request page — where, between two and three in the morning, merges scroll past like a waterfall. Sixty-something of them, all plugin entries.
Your first reaction is probably that this looks arbitrary, and your PR will drown. Your second is: did anyone actually read all of those?
Both questions have definite answers, and the answers are written into the repository’s admission rules.
61 entries in one hour is the design, not a runaway
Start with the facts. Between 02:14 and 03:19 UTC on November 8, NousResearch/hermes-agent merged 61 plugin catalog entries. The labels are uniform: all carry ci-reviewed, most carry comp/plugins, a smaller set type/feature with P3.
Nobody was clicking merge at random all night. Admission rule 5 allows exactly two paths:
- the plugin repository’s owner or a major contributor submits the entry;
- maintainers add entries in batches from a reviewed sweep of community plugins — “every pin validated and scanned at the pinned commit”.
So batch admission is an official way of working. What is batched is the cadence of PRs, not the density of checks. Every entry goes through the same gate.
One more thing worth knowing: being swept in does not take control away from the author. A PR from the owner adjusting or removing their entry is accepted on request, and later SHA bumps (rule 4) remain owner-or-maintainer PRs.
What each entry goes through during a sweep
If all you want is the checklist, this is it. The command reviewers and CI run is the same one you can run locally:
hermes plugins validate /path/to/your-plugin --install-deps
What it checks is not “does it run” but a list of things that are easy to overlook:
- the
plugin.yamlmanifest and whetherrequires_hermesholds; - that the plugin actually loads — at the pinned commit;
- that the
capabilitiesyou declare (tools, hooks, middleware, env) match what the plugin registers — this one fails rather than warns, because quiet capability creep is treated as a security issue; config_schemaandrequires_env;- that Python dependencies resolve inside Hermes’s core constraints;
- the install security scanner (
dangerousblocks;cautionbecomes a warning a reviewer reads); - the
desktop surfaceandno core overridechecks.
Those last two are the catalog’s hardest values and deserve their own paragraph. Desktop plugins may use only the SDK — no patching the renderer or browser prototypes. No plugin may override Hermes core at runtime — no AIAgent.<method> = ..., no sys.modules[...], no writing into a core module’s tables. The docs give the reason plainly: two plugins patching the same seam silently break each other, and every core release can break both.
The cheapest mindset for an author is therefore: stop patching around it and ask for a hook. If a capability is missing, open an issue. The project says outright that it would rather add a seam than list a patch.
Two edge cases in this wave that show the real friction
A batch sweep is not just the merge button. It grinds against corners you never see otherwise. This wave had two.
One: eight entries whose author repositories refuse maintainer pushes. Catalog CI has to clone the author’s repository and run validation at the pinned commit. Some repositories protect branches or restrict permissions, so a maintainer cannot push to them — even a marker branch. A dedicated PR (#150957) lists those eight entries so they can be handled separately. The lesson is collaborative, not technical: if you want your plugin swept in cleanly, do not lock the maintainers’ automation out of your repo.
Two: rule 17’s archive scan treated data files as payloads. Rule 17 forbids “unscannable executable payloads”, implemented by scanning the plugin’s archives. One entry in this wave (dike) pins a data corpus tarball: 34k .json files, two .ttl files, and .jsonld context files. The scanner did not recognise .jsonld or .ttl, so it classified the corpus as an unscannable payload and the entry failed pinned-source validation.
The fix (commit 11b2b4414f) argues from first principles: JSON-LD and Turtle are plain-text RDF serialisations, exactly as reviewable as the .json and .xml already on the source list — they are not payloads. The wording is worth reading, because it captures the attitude behind the rules: the point is reviewability, not looking tidy.
If you want to be listed, these seven things matter more than your code
In document order, the reasons entries come back are almost always preparation, not a lack of cleverness.
One: pin a full 40-character commit SHA. Branches, tags and short SHAs are rejected by the loader. Installing clones your repo and checks out exactly that commit — that is the entire trust model.
Two: do not ship a self-updater. Rule 3 forbids plugins that fetch and replace their own files (in-app “check for updates”, signed release downloaders, remote plugin.js loaders). A self-updater means an installed copy can move to a commit nobody reviewed. Want to update? Open a SHA-bump PR; users run hermes plugins update <name>.
Three: declared capabilities must match reality. Over-declaring is wasteful, under-declaring is a security problem, and there is no negotiation on this one.
Four: use public surfaces, do not patch. Hooks, middleware, ctx.register_*, provider profiles, the Desktop SDK — that is the list. Ask for what is missing instead of routing around it.
Five: credentials come through Hermes. Rule 11 is detailed about it: secrets declared in requires_env and config_schema 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); third-party OAuth clients are declared under oauth: in plugin.yaml and signed in with hermes auth add <plugin>:<id>; a plugin never reads .env files, auth.json, another tool’s login state, or a keychain.
Six: disclose risky behaviour. Rule 13 asks for what a user would want to know before installing: network calls, reads outside the plugin’s own data, shell commands, long-running background processes, stored credentials — in the PR description and the README. Telemetry must be opt-in. Reviewers turn these into disclosure lines on the entry. Being found out costs more than writing it down up front.
Seven: requires_hermes must be honest. It is a SemVer floor (">=0.21.5"), not a date, and never newer than the current release. It is also enforced: installing by catalog name refuses on a Hermes it rejects, and hermes plugins update keeps an installed plugin at its current pin until Hermes is updated.
What listing gets you
For users, the value is “install by name, at the commit a maintainer read”. The entry points:
hermes plugins search <keyword>
hermes plugins browse
hermes plugins show <name>
hermes plugins install <name>
hermes plugins capabilities <name>
show prints the entry’s details (including the events it emits and listens to), and capabilities compares declared against granted permissions — worth a glance before you install rather than a surprise afterwards.
The catalog’s trust model itself (human review, SHA pins, the removed.yaml blocklist) is covered in the catalog introduction; the fussier rejection reasons at the CI gate (renamed entries, a subdir escaping the pinned clone, a sha naming a tag object) have their own case study in this post about the CI gate. This one adds the third piece: batch admission as a way of working, and what it means if you are the author.
Status
This wave merged on main on November 8 and is not part of v0.23.0 — but catalog entries are data files, so they are not tied to release cadence: as long as your Hermes can reach the catalog, new entries can be searched and installed (whether an install succeeds depends on the entry’s requires_hermes and your version).
If you are preparing your own entry, the site’s hermes plugins reference lists the full subcommand surface — do not memorise only install.