Herm plugin system overview: extend the terminal UI

Herm plugins are bundled TypeScript modules that register into the TUI at startup. A plugin exports a HermPlugin object with an id, optional enabled flag, and a tui(api) factory.

Herm does not load external npm or user-directory plugins yet. Current plugins must be compiled into the Herm bundle through src/plugins/internal.ts.

What plugins can do today

Plugins can register UI, routes, commands, gateway event listeners, namespaced state, lifecycle cleanup, and Eikon rasterizers.

Slots: inject UI into mounted host regions

Herm’s public slot type lists several possible slots. In the current host, app_bottom is the mounted plugin slot. It renders in the one-row gutter below the composer and receives { sid, tab, streaming }.The app_bottom call site uses single_winner composition. The contribution with the lowest order wins.

Routes: add a top-level tab

Register a named route and Herm appends it after the built-in tabs. Navigate to a plugin route with api.route.navigate("RouteName").

Commands: add command-palette entries

Register commands with a title, value, optional description, optional category, and onSelect callback. They appear in the Ctrl+K command palette.

Events: listen to gateway traffic

Subscribe to the live gateway event stream with api.event.on(fn). Use it for UI updates, toasts, or route changes that react to Hermes Agent state.

Eikon rasterizers: add render backends

Register a rasterizer for Eikon Studio. Studio owns cropping, state selection, playback, and knob UI. Your rasterizer maps the prepared window to terminal frames.

Add a bundled plugin

Create a bundled module

Add a module under src/plugins/bundled/. It must export a default HermPlugin value.

import type { HermPlugin } from "../types"

const plugin: HermPlugin = {
  id: "acme.hello",
  enabled: false,
  tui(api) {
    api.slots.register({
      order: 50,
      slots: {
        app_bottom: () => (
          <text fg={api.theme.current.textMuted}>hello from acme</text>
        ),
      },
    })
  },
}

export default plugin

Import the module in src/plugins/internal.ts and append it to INTERNAL.

import hello from "./bundled/hello"

export const INTERNAL: ReadonlyArray<HermPlugin> = [
  clock,
  files,
  hello,
]

Default enablement

Plugins are enabled by default unless they set enabled: false. User toggles in the plugin manager override the compiled default and persist across launches. The bundled demo plugins, demo.clock and demo.files, ship disabled by default.

Persistent plugin state

Herm stores local plugin state in ~/.hermes/herm/tui.json, or $HERM_CONFIG_DIR/tui.json when set.

plugin.enabled stores per-plugin enablement overrides.
api.kv stores plugin data under keys scoped by plugin id.

When to build a plugin

Build a bundled plugin when you need a small Herm UI extension, a custom route, command-palette action, gateway event reaction, local plugin setting, or Eikon rasterizer. Do not use the plugin API for model providers, gateway RPC definitions, Hermes Agent tool execution, or Eikon package/catalog contract changes. Those belong to Hermes Agent or Eikon.

Get Started

Core Features

Eikon Avatars

Customization

Plugins

Troubleshooting

Herm plugin system overview: extend the terminal UI

What plugins can do today

Add a bundled plugin

Default enablement

Persistent plugin state

When to build a plugin

​What plugins can do today

​Add a bundled plugin

​Default enablement

​Persistent plugin state

​When to build a plugin

​Related docs

What plugins can do today

Add a bundled plugin

Default enablement

Persistent plugin state

When to build a plugin

Related docs