Files

Teknium 72250b5f62 feat: config-gated /verbose command for messaging gateway (#3262 )

* feat: config-gated /verbose command for messaging gateway

Add gateway_config_gate field to CommandDef, allowing cli_only commands
to be conditionally available in the gateway based on a config value.

- CommandDef gains gateway_config_gate: str | None — a config dotpath
  that, when truthy, overrides cli_only for gateway surfaces
- /verbose uses gateway_config_gate='display.tool_progress_command'
- Default is off (cli_only behavior preserved)
- When enabled, /verbose cycles tool_progress mode (off/new/all/verbose)
  in the gateway, saving to config.yaml — same cycle as the CLI
- Gateway helpers (help, telegram menus, slack mapping) dynamically
  check config to include/exclude config-gated commands
- GATEWAY_KNOWN_COMMANDS always includes config-gated commands so
  the gateway recognizes them and can respond appropriately
- Handles YAML 1.1 bool coercion (bare 'off' parses as False)
- 8 new tests for the config gate mechanism + gateway handler

* docs: document gateway_config_gate and /verbose messaging support

- AGENTS.md: add gateway_config_gate to CommandDef fields
- slash-commands.md: note /verbose can be enabled for messaging, update Notes
- configuration.md: add tool_progress_command to display section + usage note
- cli.md: cross-link to config docs for messaging enablement
- messaging/index.md: show tool_progress_command in config snippet
- plugins.md: add gateway_config_gate to register_command parameter table

2026-03-26 14:41:04 -07:00

3.7 KiB

Raw Blame History

sidebar_position

sidebar_position
20

Plugins

Hermes has a plugin system for adding custom tools, hooks, slash commands, and integrations without modifying core code.

→ Build a Hermes Plugin — step-by-step guide with a complete working example.

Quick overview

Drop a directory into ~/.hermes/plugins/ with a plugin.yaml and Python code:

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # manifest
├── __init__.py      # register() — wires schemas to handlers
├── schemas.py       # tool schemas (what the LLM sees)
└── tools.py         # tool handlers (what runs when called)

Start Hermes — your tools appear alongside built-in tools. The model can call them immediately.

Project-local plugins under ./.hermes/plugins/ are disabled by default. Enable them only for trusted repositories by setting HERMES_ENABLE_PROJECT_PLUGINS=true before starting Hermes.

What plugins can do

Capability	How
Add tools	`ctx.register_tool(name, schema, handler)`
Add hooks	`ctx.register_hook("post_tool_call", callback)`
Add slash commands	`ctx.register_command("mycommand", handler)`
Ship data files	`Path(__file__).parent / "data" / "file.yaml"`
Bundle skills	Copy `skill.md` to `~/.hermes/skills/` at load time
Gate on env vars	`requires_env: [API_KEY]` in plugin.yaml
Distribute via pip	`[project.entry-points."hermes_agent.plugins"]`

Plugin discovery

Source	Path	Use case
User	`~/.hermes/plugins/`	Personal plugins
Project	`.hermes/plugins/`	Project-specific plugins (requires `HERMES_ENABLE_PROJECT_PLUGINS=true`)
pip	`hermes_agent.plugins` entry_points	Distributed packages

Available hooks

Plugins can register callbacks for these lifecycle events. See the Event Hooks page for full details, callback signatures, and examples.

Hook	Fires when
`pre_tool_call`	Before any tool executes
`post_tool_call`	After any tool returns
`pre_llm_call`	Before LLM API request (planned)
`post_llm_call`	After LLM API response (planned)
`on_session_start`	Session begins (planned)
`on_session_end`	Session ends (planned)

Slash commands

Plugins can register slash commands that work in both CLI and messaging platforms:

def register(ctx):
    ctx.register_command(
        name="greet",
        handler=lambda args: f"Hello, {args or 'world'}!",
        description="Greet someone",
        args_hint="[name]",
        aliases=("hi",),
    )

The handler receives the argument string (everything after /greet) and returns a string to display. Registered commands automatically appear in /help, tab autocomplete, Telegram bot menu, and Slack subcommand mapping.

Parameter	Description
`name`	Command name without slash
`handler`	Callable that takes `args: str` and returns `str
`description`	Shown in `/help`
`args_hint`	Usage hint, e.g. `"[name]"`
`aliases`	Tuple of alternative names
`cli_only`	Only available in CLI
`gateway_only`	Only available in messaging platforms
`gateway_config_gate`	Config dotpath (e.g. `"display.my_option"`). When set on a `cli_only` command, the command becomes available in the gateway if the config value is truthy.

Managing plugins

/plugins              # list loaded plugins in a session
hermes config set display.show_cost true  # show cost in status bar

See the full guide for handler contracts, schema format, hook behavior, error handling, and common mistakes.

3.7 KiB Raw Blame History