Plugin System & Plugin Catalog
Relevant source files
The following files were used as context for generating this wiki page:
The Plugin System and Plugin Catalog provide a curated, secure infrastructure for extending the Hermes Agent's capabilities. This system allows users to discover, install, and manage plugins through a centralized catalog that enforces strict trust signals and security policies. Plugins integrate with the agent to provide new tools, hooks, and middleware while adhering to exact version pinning to ensure system stability.
The catalog serves as a "human-merged gate," where every entry undergoes review by maintainers before admission. This process ensures that plugins do not contain self-updating code or undeclared capabilities that could compromise the host environment. Users interact with this system via the Hermes CLI or the Desktop interface to search for and install official or community-contributed extensions.
Sources: plugin-catalog/README.md:1-15, website/src/components/PluginCatalog/PluginPage.tsx:135-150
Admission and Security Policy
The Plugin Catalog operates on a trust model defined by manual review and immutable references. To maintain security, the system enforces several hardline rules for any plugin seeking admission to the catalog.
Core Security Requirements
- Human-Merged Gate: Maintainers must review and merge a Pull Request (PR) to the
hermes-agentrepository for every catalog entry. Automated ingestion is not permitted. - Exact SHA Pins: Every plugin must pin a full 40-character commit SHA. The loader rejects branches, tags, or short SHAs.
- No Self-Updating Code: Plugins are prohibited from fetching or replacing their own files. This ensures that the code running on a user's machine is exactly what was reviewed.
- Capability Validation: The
capabilities:block in the plugin manifest (defining tools, hooks, and middleware) must match the actual code at the pinned commit. - Security Scanning: The
hermes plugins validatecommand runs a security scan during admission. "Dangerous" findings fail the entry, while "Caution" findings require manual reviewer approval.
Sources: plugin-catalog/README.md:8-45
Desktop Plugin Restrictions
Plugins running in the Desktop renderer are isolated for errors but not capabilities. Therefore, they must stay within the provided SDK surface. Prohibited actions include:
- Prototype patching (e.g.,
Object.defineProperty(...prototype)). - Use of
evalornew Function. - Script-tag injection or reaching into internal app stores.
Sources: plugin-catalog/README.md:46-55
Plugin Entry Schema
Each plugin is defined by a YAML manifest in the catalog directory. This manifest contains metadata used for discovery, installation, and documentation generation.
| Field | Type | Description |
|---|---|---|
name | String | The catalog key (lowercase, alphanumeric, hyphens). |
repo | URL | The HTTPS URL of the plugin repository. |
sha | String | Mandatory 40-hex commit SHA. |
tier | String | official or community. |
category | String | Shelf location (e.g., memory, desktop, tools, models). |
capabilities | Object | Defines provides_tools, provides_hooks, and requires_env. |
requires_hermes | String | Version constraint (e.g., >=0.19). |
Sources: plugin-catalog/README.md:66-90
Architecture and Data Flow
The Plugin System follows a structured lifecycle from PR submission to local installation and execution.
Plugin Admission Flow
The following diagram illustrates the process of adding a new plugin to the official catalog.
The diagram shows the validation steps required before a plugin becomes discoverable.
Sources: plugin-catalog/README.md:8-55
Installation Sequence
When a user requests an installation, the system ensures the local environment matches the reviewed state.
This sequence ensures that the exact pinned commit is retrieved and verified.
Sources: plugin-catalog/README.md:15-20, website/src/components/PluginCatalog/PluginPage.tsx:145-160
Plugin Management and Removal
The system distinguishes between "delisting" and "removal" to handle unmaintained or malicious plugins.
Blocklist (removed.yaml)
When a plugin is pulled for security or policy violations, it is recorded in removed.yaml. The installer refuses to install any plugin matching a name or repository URL found in this blocklist. This prevents malicious plugins from being re-installed via stale identifiers.
Delisting
Entries that are merely unmaintained or superseded are deleted from the catalog file. This does not affect users who have already installed the plugin but prevents new installations.
Sources: plugin-catalog/README.md:103-112
Integration with Agent Skills
Plugins often work in tandem with the Agent's Skill system. Skills provide the logic for the agent to use the tools exposed by plugins.
Skill Authoring Standards
When authoring skills to interact with plugins, developers must follow "Hardline" standards:
- Hermes-tool framing: Reference tools by name in backticks (e.g.,
terminal,read_file). - Invoke via terminal: Frame running plugin scripts as "invoke through the
terminaltool." - Environment Hygiene: Skills must ignore invisible or bidirectional Unicode control characters in source data to prevent prompt injection or "Trojan Source" attacks.
Sources: agent/learn_prompt.py:22-80, skills/software-development/hermes-agent-skill-authoring/SKILL.md:120-135
Platform Gating
Skills and plugins can be gated by host OS using the platforms: field. This prevents the agent from attempting to use platform-specific primitives (like osascript for macOS or systemctl for Linux) on unsupported systems.
| Prerequisite | Platform Tag |
|---|---|
osascript, defaults | [macos] |
apt, systemctl, /proc | [linux] |
| Cross-platform Python/CLI | [linux, macos, windows] |
Sources: skills/software-development/hermes-agent-skill-authoring/SKILL.md:85-100
Catalog Visualization and Documentation
The project automatically generates documentation for every catalog entry. The build process fetches the README from the pinned SHA and renders it through an allowlist (stripping raw HTML and resolving links against the pinned tree).
Plugin Page Components
The PluginPage.tsx component renders the following information for users:
- Hero Section: Displays the plugin name, tier pill (Official/Community), version, and GitHub stars.
- Capabilities Section: Lists the specific Tools, Hooks, and Middleware provided by the plugin.
- Installation Actions: Provides a "Open in Hermes Desktop" link and a copyable CLI install command.
- Source Links: Links to the repository and the specific "Reviewed Source" at the pinned SHA.
Sources: website/src/components/PluginCatalog/PluginPage.tsx:75-130, plugin-catalog/README.md:92-101
The Plugin System ensures that the Hermes Agent remains extensible while prioritizing security through manual curation, strict versioning, and capability validation. By separating the plugin code from the agent core and enforcing a reviewed admission process, the system provides a stable environment for both developers and users.