72250b5f62
* 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
96 lines
3.7 KiB
Markdown
96 lines
3.7 KiB
Markdown
---
|
|
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](/docs/guides/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](/docs/user-guide/features/hooks#plugin-hooks)** 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:
|
|
|
|
```python
|
|
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 | None` |
|
|
| `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](/docs/guides/build-a-hermes-plugin)** for handler contracts, schema format, hook behavior, error handling, and common mistakes.
|