> ## Documentation Index
> Fetch the complete documentation index at: https://herm.liftaris.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Herm plugin system overview: extend the terminal UI

> Understand Herm's bundled plugin API, current host-mounted extension points, route and command registration, lifecycle cleanup, and current loading limits.

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.

<Warning>
  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`.
</Warning>

## What plugins can do today

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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")`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Add a bundled plugin

<Steps>
  <Step title="Create a bundled module">
    Add a module under `src/plugins/bundled/`. It must export a default `HermPlugin` value.

    ```tsx theme={null}
    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
    ```
  </Step>

  <Step title="Register it in internal.ts">
    Import the module in `src/plugins/internal.ts` and append it to `INTERNAL`.

    ```ts theme={null}
    import hello from "./bundled/hello"

    export const INTERNAL: ReadonlyArray<HermPlugin> = [
      clock,
      files,
      hello,
    ]
    ```
  </Step>
</Steps>

## 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.

## Related docs

* [Plugin API reference](/plugins/api-reference)
* [Plugin examples](/plugins/examples)
* [Themes](/customization/themes)