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-platform

Plugin platform

Hermes plugins are optional extensions that add provider profiles, tools, chat platforms, agent behavior, and product surfaces without changing the core agent flow. The platform treats a plugin as a declared and governed unit: it finds the plugin, checks what it asks for, publishes it safely, runs it within a defined trust boundary, and keeps its live registrations tied to the plugin that owns them. See Plugin lifecycle and integration for the detailed lifecycle and runtime contracts.

Extension model

The plugin platform connects third-party code to named Hermes extension points. A plugin exposes capabilities through a manifest and a registration context, while Hermes keeps routing, policy, state ownership, and cleanup under host control.

Extension categories

Plugins extend Hermes at several product boundaries. The same platform supports both background integrations and user-facing features, so a plugin can add a provider or tool without becoming a separate application.

CategoryProduct role
ProvidersSupply model, web search, browser, media, speech, terminal, secret, memory, or context services.
Tools and skillsAdd actions or reusable agent abilities to sessions.
PlatformsConnect Hermes to an inbound or outbound chat service.
Hooks and middlewareObserve or shape agent, tool, gateway, approval, and session events through named contracts.
Product surfacesAdd commands, dashboard pages, dashboard slots, language packs, prompt sections, and auxiliary tasks.

References: hermes_cli/plugins.py• L455-498 hermes_cli/plugins.py• L685-808 hermes_cli/plugins.py• L933-1011 web/…/registry.ts• L63-191

Profile scope

Plugin selection and plugin-owned data belong to a Hermes profile. This keeps one profile's providers, settings, credentials, and registrations from leaking into another profile when one process serves many profiles.

References: hermes_cli/plugins.py• L1153-1239 hermes_cli/plugins_state.py• L134-195 providers/__init__.py• L67-90

Discovery and admission

Discovery turns possible plugin sources into candidate manifests. Admission then decides which candidate is trusted, compatible, enabled, and safe enough to publish; finding a plugin does not by itself execute or activate it.

Plugin sources

Hermes can discover bundled plugins, profile-local plugins, opt-in project plugins, and installed Python packages that advertise the Hermes plugin entry-point group. The Desktop app also probes Git repositories and optional subdirectories for desktop plugin artifacts. Later sources can replace an earlier plugin with the same identity, while project discovery stays explicitly disabled unless the operator opts in.

References: hermes_cli/plugins_discovery.py• L134-218 hermes_cli/plugins_discovery.py• L221-243 hermes_cli/plugins_discovery.py• L72-100 apps/…/desktop-plugin-install.ts• L66-121 apps/…/desktop-plugin-install.ts• L475-509

Manifest contract

A manifest gives Hermes the identity, kind, compatibility, dependencies, declared capabilities, configuration shape, and product surfaces of a plugin before normal runtime loading. Hermes accepts older manifest forms, ignores unknown fields for forward compatibility, and treats plugin-to-plugin dependencies as load-order advice rather than a reason to remove the dependent plugin.

References: hermes_cli/plugins_manifest.py• L27-42 hermes_cli/plugins_manifest.py• L129-184 hermes_cli/plugins_manifest.py• L219-265

Trust and compatibility gates

Admission checks the candidate tree before it can replace the installed tree. The checks cover manifest shape, Hermes version requirements, declared environment and configuration data, actual registered capabilities, security findings, and product-surface rules. Capability consent is separate from installation: an installed plugin may remain unable to use a gated action until the operator grants it.

References: hermes_cli/plugin_validate.py• L1-11 hermes_cli/plugins_cmd.py• L183-225 hermes_cli/plugin_capabilities.py• L27-51 hermes_cli/plugin_capabilities.py• L161-210

Installation and publication

Installation changes a profile in stages so untrusted or incomplete code does not become the live plugin by accident. Hermes obtains a candidate, checks it, prepares dependencies and required environment values with user consent, then publishes the candidate and its provenance as one recoverable change.

Installation transaction

The install flow stages the source outside the live plugin directory. It reads and validates the manifest, scans the final staged tree, checks portable package availability, prepares dependencies through the Hermes package manager, and only then publishes the tree and install record. A declined dependency decision leaves the plugin installed but disabled rather than silently changing the active environment.

References: hermes_cli/plugins_cmd_install.py• L331-359 hermes_cli/plugins_cmd_install.py• L377-429 hermes_cli/plugins_cmd_install.py• L470-491 hermes_cli/plugins_transaction.py• L16-49

Desktop installation

The Desktop Git installer separates review from publication. It probes a temporary clone, identifies whether the source has an agent half, a desktop half, or both, and records the reviewed commit. Installation uses that exact commit, so a source that moves after review is refused instead of silently changing the code being installed.

The installer publishes only a checked desktop tree into the app-level desktop plugin root. A unified package uses the agent package name and a marker so the Desktop copy stays paired with its agent half; a desktop-only repository remains independent. Staging and a shared root lock keep incomplete copies and concurrent reconcile passes out of the live root.

References: apps/…/desktop-plugin-install.ts• L263-320 apps/…/desktop-plugin-install.ts• L423-447 apps/…/desktop-plugin-install.ts• L522-615 apps/…/desktop-plugins-root.ts• L74-96 apps/…/desktop-plugins-root.ts• L369-469

Provenance records

Hermes records how a plugin entered the profile so later update decisions do not rely on claims inside plugin code. A tracked Git installation can be updated from its approved source, a manual copy is not auto-updatable, and a mismatch between the recorded source and the installed tree is treated as drift that needs repair.

References: hermes_cli/plugins_provenance.py• L1-15 hermes_cli/plugins_provenance.py• L28-43 hermes_cli/plugins_provenance.py• L106-141

Runtime activation

Activation converts an admitted plugin into live registrations that Hermes can route to. Hermes records ownership for each registration, which lets it remove or replace a plugin without leaving stale tools, hooks, providers, platform handlers, or product entries behind.

Registration boundary

The plugin receives a controlled context rather than the core's private registries. Through that context it can register public extension types, read or write namespaced settings, keep profile-scoped state, and request gated actions. Hermes checks types and conflicts at the boundary and tracks each accepted registration for later teardown.

References: hermes_cli/plugins.py• L230-285 hermes_cli/plugins.py• L296-373 hermes_cli/plugins.py• L455-498 hermes_cli/plugins_state.py• L24-90

Activation timing

An installed or enabled plugin can become partly useful without a full process restart. Gateway commands, transforms, platform callbacks, locales, portable MCP connections, and skills can become live during activation, while Python tools and prompt sections wait for a new session to preserve prompt and tool-cache behavior.

This diagram shows the handoff from a published plugin to the surfaces that can use it immediately or later.

flowchart LR
    A[Published and enabled plugin] --> B[Profile discovery]
    B --> C[Registration ledger]
    C --> D[Gateway handlers and callbacks]
    C --> E[Skills and MCP connections]
    C --> F[Next-session tools and prompt sections]
    D --> G[Live gateway]
    E --> H[Open chats]
    F --> I[New session]

References: hermes_cli/plugins_activation.py• L24-74 hermes_cli/plugins_activation.py• L96-127 hermes_cli/plugins_activation_live.py• L1-13

Product-surface integration

Product surfaces use the same trust and enablement decisions as runtime plugins. Dashboard metadata can add a tab, replace a route, fill a named slot, load browser assets, or expose a protected API route; the browser SDK supplies the approved API, authentication, UI, and slot interfaces. The Desktop app loads its own app-level plugin root for panes, palette commands, themes, and other native product surfaces, separate from profile-owned agent execution.

References: hermes_cli/web_server_dashboard.py• L517-589 hermes_cli/web_server_dashboard.py• L869-895 web/…/registry.ts• L99-191 apps/…/desktop-plugins-root.ts• L1-17 apps/…/desktop-plugins-root.ts• L138-186

Isolation boundary

Isolation controls whether user plugin code shares the Hermes interpreter. In-process mode gives the plugin the normal runtime path; host mode moves supported third-party code to one plugin-host process per profile so a plugin failure does not directly stop Hermes or mix code between profiles.

Host process

The host process runs plugin code and forwards approved context calls to Hermes as data or controlled proxies. Hermes still owns registries, policy checks, profile scope, and lifecycle cleanup, so the rest of the system sees ordinary registrations while the plugin code stays outside the main process.

References: hermes_cli/plugin_isolation.py• L1-17 hermes_cli/plugin_isolation.py• L32-73 hermes_cli/plugin_host.py• L1-18 hermes_cli/plugin_host.py• L202-252

Isolation limits

Some extensions need live SDK clients, event-loop objects, or launch-scope services. Those surfaces remain in-process or are refused in host mode; supported provider objects and data-only facades can cross the boundary. A host crash makes its proxies unavailable, then Hermes performs bounded recovery and avoids repeatedly reloading a plugin that keeps killing the host.

References: hermes_cli/plugin_isolation.py• L32-73 hermes_cli/plugin_isolation.py• L114-135 hermes_cli/plugin_host.py• L141-182

Update and removal

Updates use the same admission and publication rules as installation. Hermes first establishes that the installed provenance is still trusted, obtains a new catalog pin or source revision, validates the staged replacement, rechecks new dependency or capability requests, and publishes only when the live tree has not changed underneath it.

Update sources

Catalog plugins move only through a newly reviewed catalog pin. Other tracked Git plugins use their recorded source or an approved update feed, while pinned, manual, drifted, and untrusted-source installations are not silently moved. Update checks are read-only until an explicit update action or the opt-in automatic apply policy runs.

References: hermes_cli/plugins_updates.py• L1-13 hermes_cli/plugins_updates.py• L133-234 hermes_cli/plugins_cadence.py• L1-8 hermes_cli/plugins_cadence.py• L181-199

Replacement and removal

Replacement preserves user-owned plugin data where the update flow identifies it and refuses to publish when dependency consent, compatibility, scanning, or file-integrity checks fail. Removal and forced rediscovery use the ownership ledger to detach registrations, cancel plugin tasks, and prevent an old registration from surviving under a new plugin version.

Desktop removal applies a separate ownership rule. A standalone desktop folder can be removed only as one direct child of the app-level root; a marked desktop half is refused because reconciliation must remove it with the agent package. Reconciliation copies the first matching package from the known local homes, refreshes it when its source changes, and prunes it only when the source is known to be gone.

References: hermes_cli/plugins_transaction.py• L51-87 hermes_cli/plugins_transaction.py• L90-208 hermes_cli/plugins.py• L1290-1327 apps/…/desktop-plugin-remove.ts• L1-82 apps/…/desktop-plugins-root.ts• L505-582

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep manifest declarations, validation probes, catalog capability data, and the actual registration surface aligned. A declaration mismatch can block admission or hide a capability.
  • Keep profile scope attached to provider registries, plugin settings, state, host processes, and activation requests. A process can serve more than one profile.
  • Keep staged publication, install metadata, dependency preparation, and enablement as one admission decision. Do not make the live tree or active environment change before the required gate passes.
  • Keep isolation support aligned across the context method tables, host wire contract, category loaders, and product-surface loaders.
  • Keep activation summaries honest about what is live now and what waits for a new session or a service reload.
  • Keep catalog SHA pins and update provenance aligned. A new catalog revision requires a reviewed catalog change.
  • Keep Desktop Git review SHAs, source detection, package markers, and the published folder name aligned. A unified package must remain paired with its agent row.
  • Keep every writer of the app-level Desktop plugin root behind the shared lock. Reconcile, install, and remove must not publish or delete the same folder at the same time.
  • Keep desktop publication plain and staged. Do not allow symlinks, an incomplete copy, or a source that is no longer readable to become a live plugin or trigger a false prune.

Important failure modes

TriggerConsequenceGuard
A plugin declares a capability that its code does not registerAdmission rejects the plugin or the product shows an incorrect trust requestIsolated validation probes compare declared and observed registrations
A user plugin is installed but not enabledIts code is not loaded into the normal runtime pathThe enable list and disable list gate discovery; product APIs apply the same gate
A plugin requests a new dependency without consentThe active environment and plugin selection remain unchangedDependency preparation runs before publication and requires an explicit answer
A plugin host exitsPlugin tools and hooks fail for that host while Hermes stays availableProxy errors are contained and host restarts are bounded
An update source or saved update tag changes unexpectedlyAutomatic update is refused until the source is reviewedProvenance reconciliation reports drift or a trust-update-url action
A plugin is enabled during an open sessionSome live handlers work but cached tools or prompt sections do not changeActivation reports immediate and deferred surfaces separately
The Git source moves between probe and installThe Desktop install may place code that the user did not reviewInstallation checks out the reviewed full commit and refuses when it is unavailable
A unified package's desktop half is removed as a standalone folderThe next reconcile restores it or the Desktop row flickersThe remover rejects folders carrying the package marker and the agent package owns the half
A reconcile pass cannot read one packageOne desktop plugin is not published, but other plugins continue to loadReconcile records the refusal and keeps the existing root copy unless the source is known to be gone

Key files

FileWhy to read it
hermes_cli/plugins.pyCentral plugin manager, context boundary, registration ownership, and discovery entry point.
hermes_cli/plugins_discovery.pyPlugin source scanning, precedence, enablement, and kind routing.
hermes_cli/plugins_manifest.pyManifest model, compatibility fields, configuration schema, and dependency order.
hermes_cli/plugin_validate.pyAdmission checks and isolated capability probing.
hermes_cli/plugins_cmd_install.pyStaged installation, consent, scanning, and enablement flow.
hermes_cli/plugins_transaction.pyRecoverable publication and update replacement rules.
hermes_cli/plugin_isolation.py and hermes_cli/plugin_host.pyIsolation modes and the profile-scoped host boundary.
hermes_cli/plugins_activation.pyImmediate versus deferred activation behavior.
hermes_cli/plugins_provenance.py and hermes_cli/plugins_updates.pyUpdate trust, provenance classes, and source checks.
plugin-catalog/README.mdCatalog trust model, reviewed pins, and admission policy.
web/…/registry.tsBrowser product-surface SDK and dashboard plugin contract.
apps/…/desktop-plugin-install.tsDesktop Git probing, reviewed-commit installs, component pairing, and staged publication.
apps/…/desktop-plugins-root.tsApp-level Desktop root, profile migration, unified package materialization, and source reconciliation.
apps/…/desktop-plugin-remove.tsSafe removal rules for standalone Desktop plugins and unified package halves.