merge: resolve conflicts with main (show_cost, turn routing, docker docs)
This commit is contained in:
teknium1
commit
f4d61c168b
59 changed files with 4528 additions and 607 deletions
438
website/docs/guides/build-a-hermes-plugin.md
Normal file
438
website/docs/guides/build-a-hermes-plugin.md
Normal file
|
|
@ -0,0 +1,438 @@
|
|||
---
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
# Build a Hermes Plugin
|
||||
|
||||
This guide walks through building a complete Hermes plugin from scratch. By the end you'll have a working plugin with multiple tools, lifecycle hooks, shipped data files, and a bundled skill — everything the plugin system supports.
|
||||
|
||||
## What you're building
|
||||
|
||||
A **calculator** plugin with two tools:
|
||||
- `calculate` — evaluate math expressions (`2**16`, `sqrt(144)`, `pi * 5**2`)
|
||||
- `unit_convert` — convert between units (`100 F → 37.78 C`, `5 km → 3.11 mi`)
|
||||
|
||||
Plus a hook that logs every tool call, and a bundled skill file.
|
||||
|
||||
## Step 1: Create the plugin directory
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.hermes/plugins/calculator
|
||||
cd ~/.hermes/plugins/calculator
|
||||
```
|
||||
|
||||
## Step 2: Write the manifest
|
||||
|
||||
Create `plugin.yaml`:
|
||||
|
||||
```yaml
|
||||
name: calculator
|
||||
version: 1.0.0
|
||||
description: Math calculator — evaluate expressions and convert units
|
||||
provides:
|
||||
tools: true
|
||||
hooks: true
|
||||
```
|
||||
|
||||
This tells Hermes: "I'm a plugin called calculator, I provide tools and hooks." That's all the manifest needs.
|
||||
|
||||
Optional fields you could add:
|
||||
```yaml
|
||||
author: Your Name
|
||||
requires_env: # gate loading on env vars
|
||||
- SOME_API_KEY # plugin disabled if missing
|
||||
```
|
||||
|
||||
## Step 3: Write the tool schemas
|
||||
|
||||
Create `schemas.py` — this is what the LLM reads to decide when to call your tools:
|
||||
|
||||
```python
|
||||
"""Tool schemas — what the LLM sees."""
|
||||
|
||||
CALCULATE = {
|
||||
"name": "calculate",
|
||||
"description": (
|
||||
"Evaluate a mathematical expression and return the result. "
|
||||
"Supports arithmetic (+, -, *, /, **), functions (sqrt, sin, cos, "
|
||||
"log, abs, round, floor, ceil), and constants (pi, e). "
|
||||
"Use this for any math the user asks about."
|
||||
),
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"expression": {
|
||||
"type": "string",
|
||||
"description": "Math expression to evaluate (e.g., '2**10', 'sqrt(144)')",
|
||||
},
|
||||
},
|
||||
"required": ["expression"],
|
||||
},
|
||||
}
|
||||
|
||||
UNIT_CONVERT = {
|
||||
"name": "unit_convert",
|
||||
"description": (
|
||||
"Convert a value between units. Supports length (m, km, mi, ft, in), "
|
||||
"weight (kg, lb, oz, g), temperature (C, F, K), data (B, KB, MB, GB, TB), "
|
||||
"and time (s, min, hr, day)."
|
||||
),
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"value": {
|
||||
"type": "number",
|
||||
"description": "The numeric value to convert",
|
||||
},
|
||||
"from_unit": {
|
||||
"type": "string",
|
||||
"description": "Source unit (e.g., 'km', 'lb', 'F', 'GB')",
|
||||
},
|
||||
"to_unit": {
|
||||
"type": "string",
|
||||
"description": "Target unit (e.g., 'mi', 'kg', 'C', 'MB')",
|
||||
},
|
||||
},
|
||||
"required": ["value", "from_unit", "to_unit"],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Why schemas matter:** The `description` field is how the LLM decides when to use your tool. Be specific about what it does and when to use it. The `parameters` define what arguments the LLM passes.
|
||||
|
||||
## Step 4: Write the tool handlers
|
||||
|
||||
Create `tools.py` — this is the code that actually executes when the LLM calls your tools:
|
||||
|
||||
```python
|
||||
"""Tool handlers — the code that runs when the LLM calls each tool."""
|
||||
|
||||
import json
|
||||
import math
|
||||
|
||||
# Safe globals for expression evaluation — no file/network access
|
||||
_SAFE_MATH = {
|
||||
"abs": abs, "round": round, "min": min, "max": max,
|
||||
"pow": pow, "sqrt": math.sqrt, "sin": math.sin, "cos": math.cos,
|
||||
"tan": math.tan, "log": math.log, "log2": math.log2, "log10": math.log10,
|
||||
"floor": math.floor, "ceil": math.ceil,
|
||||
"pi": math.pi, "e": math.e,
|
||||
"factorial": math.factorial,
|
||||
}
|
||||
|
||||
|
||||
def calculate(args: dict, **kwargs) -> str:
|
||||
"""Evaluate a math expression safely.
|
||||
|
||||
Rules for handlers:
|
||||
1. Receive args (dict) — the parameters the LLM passed
|
||||
2. Do the work
|
||||
3. Return a JSON string — ALWAYS, even on error
|
||||
4. Accept **kwargs for forward compatibility
|
||||
"""
|
||||
expression = args.get("expression", "").strip()
|
||||
if not expression:
|
||||
return json.dumps({"error": "No expression provided"})
|
||||
|
||||
try:
|
||||
result = eval(expression, {"__builtins__": {}}, _SAFE_MATH)
|
||||
return json.dumps({"expression": expression, "result": result})
|
||||
except ZeroDivisionError:
|
||||
return json.dumps({"expression": expression, "error": "Division by zero"})
|
||||
except Exception as e:
|
||||
return json.dumps({"expression": expression, "error": f"Invalid: {e}"})
|
||||
|
||||
|
||||
# Conversion tables — values are in base units
|
||||
_LENGTH = {"m": 1, "km": 1000, "mi": 1609.34, "ft": 0.3048, "in": 0.0254, "cm": 0.01}
|
||||
_WEIGHT = {"kg": 1, "g": 0.001, "lb": 0.453592, "oz": 0.0283495}
|
||||
_DATA = {"B": 1, "KB": 1024, "MB": 1024**2, "GB": 1024**3, "TB": 1024**4}
|
||||
_TIME = {"s": 1, "ms": 0.001, "min": 60, "hr": 3600, "day": 86400}
|
||||
|
||||
|
||||
def _convert_temp(value, from_u, to_u):
|
||||
# Normalize to Celsius
|
||||
c = {"F": (value - 32) * 5/9, "K": value - 273.15}.get(from_u, value)
|
||||
# Convert to target
|
||||
return {"F": c * 9/5 + 32, "K": c + 273.15}.get(to_u, c)
|
||||
|
||||
|
||||
def unit_convert(args: dict, **kwargs) -> str:
|
||||
"""Convert between units."""
|
||||
value = args.get("value")
|
||||
from_unit = args.get("from_unit", "").strip()
|
||||
to_unit = args.get("to_unit", "").strip()
|
||||
|
||||
if value is None or not from_unit or not to_unit:
|
||||
return json.dumps({"error": "Need value, from_unit, and to_unit"})
|
||||
|
||||
try:
|
||||
# Temperature
|
||||
if from_unit.upper() in {"C","F","K"} and to_unit.upper() in {"C","F","K"}:
|
||||
result = _convert_temp(float(value), from_unit.upper(), to_unit.upper())
|
||||
return json.dumps({"input": f"{value} {from_unit}", "result": round(result, 4),
|
||||
"output": f"{round(result, 4)} {to_unit}"})
|
||||
|
||||
# Ratio-based conversions
|
||||
for table in (_LENGTH, _WEIGHT, _DATA, _TIME):
|
||||
lc = {k.lower(): v for k, v in table.items()}
|
||||
if from_unit.lower() in lc and to_unit.lower() in lc:
|
||||
result = float(value) * lc[from_unit.lower()] / lc[to_unit.lower()]
|
||||
return json.dumps({"input": f"{value} {from_unit}",
|
||||
"result": round(result, 6),
|
||||
"output": f"{round(result, 6)} {to_unit}"})
|
||||
|
||||
return json.dumps({"error": f"Cannot convert {from_unit} → {to_unit}"})
|
||||
except Exception as e:
|
||||
return json.dumps({"error": f"Conversion failed: {e}"})
|
||||
```
|
||||
|
||||
**Key rules for handlers:**
|
||||
1. **Signature:** `def my_handler(args: dict, **kwargs) -> str`
|
||||
2. **Return:** Always a JSON string. Success and errors alike.
|
||||
3. **Never raise:** Catch all exceptions, return error JSON instead.
|
||||
4. **Accept `**kwargs`:** Hermes may pass additional context in the future.
|
||||
|
||||
## Step 5: Write the registration
|
||||
|
||||
Create `__init__.py` — this wires schemas to handlers:
|
||||
|
||||
```python
|
||||
"""Calculator plugin — registration."""
|
||||
|
||||
import logging
|
||||
|
||||
from . import schemas, tools
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Track tool usage via hooks
|
||||
_call_log = []
|
||||
|
||||
def _on_post_tool_call(tool_name, args, result, task_id, **kwargs):
|
||||
"""Hook: runs after every tool call (not just ours)."""
|
||||
_call_log.append({"tool": tool_name, "session": task_id})
|
||||
if len(_call_log) > 100:
|
||||
_call_log.pop(0)
|
||||
logger.debug("Tool called: %s (session %s)", tool_name, task_id)
|
||||
|
||||
|
||||
def register(ctx):
|
||||
"""Wire schemas to handlers and register hooks."""
|
||||
ctx.register_tool(name="calculate", toolset="calculator",
|
||||
schema=schemas.CALCULATE, handler=tools.calculate)
|
||||
ctx.register_tool(name="unit_convert", toolset="calculator",
|
||||
schema=schemas.UNIT_CONVERT, handler=tools.unit_convert)
|
||||
|
||||
# This hook fires for ALL tool calls, not just ours
|
||||
ctx.register_hook("post_tool_call", _on_post_tool_call)
|
||||
```
|
||||
|
||||
**What `register()` does:**
|
||||
- Called exactly once at startup
|
||||
- `ctx.register_tool()` puts your tool in the registry — the model sees it immediately
|
||||
- `ctx.register_hook()` subscribes to lifecycle events
|
||||
- If this function crashes, the plugin is disabled but Hermes continues fine
|
||||
|
||||
## Step 6: Test it
|
||||
|
||||
Start Hermes:
|
||||
|
||||
```bash
|
||||
hermes
|
||||
```
|
||||
|
||||
You should see `calculator: calculate, unit_convert` in the banner's tool list.
|
||||
|
||||
Try these prompts:
|
||||
```
|
||||
What's 2 to the power of 16?
|
||||
Convert 100 fahrenheit to celsius
|
||||
What's the square root of 2 times pi?
|
||||
How many gigabytes is 1.5 terabytes?
|
||||
```
|
||||
|
||||
Check plugin status:
|
||||
```
|
||||
/plugins
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Plugins (1):
|
||||
✓ calculator v1.0.0 (2 tools, 1 hooks)
|
||||
```
|
||||
|
||||
## Your plugin's final structure
|
||||
|
||||
```
|
||||
~/.hermes/plugins/calculator/
|
||||
├── plugin.yaml # "I'm calculator, I provide tools and hooks"
|
||||
├── __init__.py # Wiring: schemas → handlers, register hooks
|
||||
├── schemas.py # What the LLM reads (descriptions + parameter specs)
|
||||
└── tools.py # What runs (calculate, unit_convert functions)
|
||||
```
|
||||
|
||||
Four files, clear separation:
|
||||
- **Manifest** declares what the plugin is
|
||||
- **Schemas** describe tools for the LLM
|
||||
- **Handlers** implement the actual logic
|
||||
- **Registration** connects everything
|
||||
|
||||
## What else can plugins do?
|
||||
|
||||
### Ship data files
|
||||
|
||||
Put any files in your plugin directory and read them at import time:
|
||||
|
||||
```python
|
||||
# In tools.py or __init__.py
|
||||
from pathlib import Path
|
||||
|
||||
_PLUGIN_DIR = Path(__file__).parent
|
||||
_DATA_FILE = _PLUGIN_DIR / "data" / "languages.yaml"
|
||||
|
||||
with open(_DATA_FILE) as f:
|
||||
_DATA = yaml.safe_load(f)
|
||||
```
|
||||
|
||||
### Bundle a skill
|
||||
|
||||
Include a `skill.md` file and install it during registration:
|
||||
|
||||
```python
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
|
||||
def _install_skill():
|
||||
"""Copy our skill to ~/.hermes/skills/ on first load."""
|
||||
try:
|
||||
from hermes_cli.config import get_hermes_home
|
||||
dest = get_hermes_home() / "skills" / "my-plugin" / "SKILL.md"
|
||||
except Exception:
|
||||
dest = Path.home() / ".hermes" / "skills" / "my-plugin" / "SKILL.md"
|
||||
|
||||
if dest.exists():
|
||||
return # don't overwrite user edits
|
||||
|
||||
source = Path(__file__).parent / "skill.md"
|
||||
if source.exists():
|
||||
dest.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy2(source, dest)
|
||||
|
||||
def register(ctx):
|
||||
ctx.register_tool(...)
|
||||
_install_skill()
|
||||
```
|
||||
|
||||
### Gate on environment variables
|
||||
|
||||
If your plugin needs an API key:
|
||||
|
||||
```yaml
|
||||
# plugin.yaml
|
||||
requires_env:
|
||||
- WEATHER_API_KEY
|
||||
```
|
||||
|
||||
If `WEATHER_API_KEY` isn't set, the plugin is disabled with a clear message. No crash, no error in the agent — just "Plugin weather disabled (missing: WEATHER_API_KEY)".
|
||||
|
||||
### Conditional tool availability
|
||||
|
||||
For tools that depend on optional libraries:
|
||||
|
||||
```python
|
||||
ctx.register_tool(
|
||||
name="my_tool",
|
||||
schema={...},
|
||||
handler=my_handler,
|
||||
check_fn=lambda: _has_optional_lib(), # False = tool hidden from model
|
||||
)
|
||||
```
|
||||
|
||||
### Register multiple hooks
|
||||
|
||||
```python
|
||||
def register(ctx):
|
||||
ctx.register_hook("pre_tool_call", before_any_tool)
|
||||
ctx.register_hook("post_tool_call", after_any_tool)
|
||||
ctx.register_hook("on_session_start", on_new_session)
|
||||
ctx.register_hook("on_session_end", on_session_end)
|
||||
```
|
||||
|
||||
Available hooks:
|
||||
|
||||
| Hook | When | Arguments |
|
||||
|------|------|-----------|
|
||||
| `pre_tool_call` | Before any tool runs | `tool_name`, `args`, `task_id` |
|
||||
| `post_tool_call` | After any tool returns | `tool_name`, `args`, `result`, `task_id` |
|
||||
| `pre_llm_call` | Before LLM API call | `messages`, `model` |
|
||||
| `post_llm_call` | After LLM response | `messages`, `response`, `model` |
|
||||
| `on_session_start` | Session begins | `session_id`, `platform` |
|
||||
| `on_session_end` | Session ends | `session_id`, `platform` |
|
||||
|
||||
Hooks are observers — they can't modify arguments or return values. If a hook crashes, it's logged and skipped; other hooks and the tool continue normally.
|
||||
|
||||
### Distribute via pip
|
||||
|
||||
For sharing plugins publicly, add an entry point to your Python package:
|
||||
|
||||
```toml
|
||||
# pyproject.toml
|
||||
[project.entry-points."hermes_agent.plugins"]
|
||||
my-plugin = "my_plugin_package"
|
||||
```
|
||||
|
||||
```bash
|
||||
pip install hermes-plugin-calculator
|
||||
# Plugin auto-discovered on next hermes startup
|
||||
```
|
||||
|
||||
## Common mistakes
|
||||
|
||||
**Handler doesn't return JSON string:**
|
||||
```python
|
||||
# Wrong — returns a dict
|
||||
def handler(args, **kwargs):
|
||||
return {"result": 42}
|
||||
|
||||
# Right — returns a JSON string
|
||||
def handler(args, **kwargs):
|
||||
return json.dumps({"result": 42})
|
||||
```
|
||||
|
||||
**Missing `**kwargs` in handler signature:**
|
||||
```python
|
||||
# Wrong — will break if Hermes passes extra context
|
||||
def handler(args):
|
||||
...
|
||||
|
||||
# Right
|
||||
def handler(args, **kwargs):
|
||||
...
|
||||
```
|
||||
|
||||
**Handler raises exceptions:**
|
||||
```python
|
||||
# Wrong — exception propagates, tool call fails
|
||||
def handler(args, **kwargs):
|
||||
result = 1 / int(args["value"]) # ZeroDivisionError!
|
||||
return json.dumps({"result": result})
|
||||
|
||||
# Right — catch and return error JSON
|
||||
def handler(args, **kwargs):
|
||||
try:
|
||||
result = 1 / int(args.get("value", 0))
|
||||
return json.dumps({"result": result})
|
||||
except Exception as e:
|
||||
return json.dumps({"error": str(e)})
|
||||
```
|
||||
|
||||
**Schema description too vague:**
|
||||
```python
|
||||
# Bad — model doesn't know when to use it
|
||||
"description": "Does stuff"
|
||||
|
||||
# Good — model knows exactly when and how
|
||||
"description": "Evaluate a mathematical expression. Use for arithmetic, trig, logarithms. Supports: +, -, *, /, **, sqrt, sin, cos, log, pi, e."
|
||||
```
|
||||
|
|
@ -34,7 +34,7 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
|
|||
| `VOICE_TOOLS_OPENAI_KEY` | Preferred OpenAI key for OpenAI speech-to-text and text-to-speech providers |
|
||||
| `HERMES_LOCAL_STT_COMMAND` | Optional local speech-to-text command template. Supports `{input_path}`, `{output_dir}`, `{language}`, and `{model}` placeholders |
|
||||
| `HERMES_LOCAL_STT_LANGUAGE` | Default language passed to `HERMES_LOCAL_STT_COMMAND` or auto-detected local `whisper` CLI fallback (default: `en`) |
|
||||
| `HERMES_HOME` | Override Hermes config directory (default: `~/.hermes`) |
|
||||
| `HERMES_HOME` | Override Hermes config directory (default: `~/.hermes`). Also scopes the gateway PID file and systemd service name, so multiple installations can run concurrently |
|
||||
|
||||
## Provider Auth (OAuth)
|
||||
|
||||
|
|
@ -79,6 +79,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
|
|||
| `TERMINAL_ENV` | Backend: `local`, `docker`, `ssh`, `singularity`, `modal`, `daytona` |
|
||||
| `TERMINAL_DOCKER_IMAGE` | Docker image (default: `python:3.11`) |
|
||||
| `TERMINAL_DOCKER_VOLUMES` | Additional Docker volume mounts (comma-separated `host:container` pairs) |
|
||||
| `TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE` | Advanced opt-in: mount the launch cwd into Docker `/workspace` (`true`/`false`, default: `false`) |
|
||||
| `TERMINAL_SINGULARITY_IMAGE` | Singularity image or `.sif` path |
|
||||
| `TERMINAL_MODAL_IMAGE` | Modal container image |
|
||||
| `TERMINAL_DAYTONA_IMAGE` | Daytona sandbox image |
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
|
|||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/help` | Show this help message |
|
||||
| `/usage` | Show token usage for the current session |
|
||||
| `/usage` | Show token usage, cost breakdown, and session duration |
|
||||
| `/insights` | Show usage insights and analytics (last 30 days) |
|
||||
| `/platforms` | Show gateway/messaging platform status |
|
||||
| `/paste` | Check clipboard for an image and attach it |
|
||||
|
|
@ -104,7 +104,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
|
|||
| `/compress` | Manually compress conversation context. |
|
||||
| `/title [name]` | Set or show the session title. |
|
||||
| `/resume [name]` | Resume a previously named session. |
|
||||
| `/usage` | Show token usage for the current session. |
|
||||
| `/usage` | Show token usage, estimated cost breakdown (input/output), context window state, and session duration. |
|
||||
| `/insights [days]` | Show usage analytics. |
|
||||
| `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display. |
|
||||
| `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | Control spoken replies in chat. `join`/`channel`/`leave` manage Discord voice-channel mode. |
|
||||
|
|
|
|||
|
|
@ -6,10 +6,28 @@ description: "Filesystem safety nets for destructive operations using shadow git
|
|||
|
||||
# Checkpoints and `/rollback`
|
||||
|
||||
Hermes Agent can automatically snapshot your project before **destructive operations** (like file write/patch tools) and restore it later with a single command.
|
||||
Hermes Agent automatically snapshots your project before **destructive operations** and lets you restore it with a single command. Checkpoints are **enabled by default** — there's zero cost when no file-mutating tools fire.
|
||||
|
||||
This safety net is powered by an internal **Checkpoint Manager** that keeps a separate shadow git repository under `~/.hermes/checkpoints/` — your real project `.git` is never touched.
|
||||
|
||||
## What Triggers a Checkpoint
|
||||
|
||||
Checkpoints are taken automatically before:
|
||||
|
||||
- **File tools** — `write_file` and `patch`
|
||||
- **Destructive terminal commands** — `rm`, `mv`, `sed -i`, `truncate`, `shred`, output redirects (`>`), and `git reset`/`clean`/`checkout`
|
||||
|
||||
The agent creates **at most one checkpoint per directory per turn**, so long-running sessions don't spam snapshots.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/rollback` | List all checkpoints with change stats |
|
||||
| `/rollback <N>` | Restore to checkpoint N (also undoes last chat turn) |
|
||||
| `/rollback diff <N>` | Preview diff between checkpoint N and current state |
|
||||
| `/rollback <N> <file>` | Restore a single file from checkpoint N |
|
||||
|
||||
## How Checkpoints Work
|
||||
|
||||
At a high level:
|
||||
|
|
@ -21,24 +39,11 @@ At a high level:
|
|||
- Stages and commits the current state with a short, human‑readable reason.
|
||||
- These commits form a checkpoint history that you can inspect and restore via `/rollback`.
|
||||
|
||||
Internally, the Checkpoint Manager:
|
||||
|
||||
- Stores shadow repos under:
|
||||
- `~/.hermes/checkpoints/<hash>/`
|
||||
- Keeps metadata about:
|
||||
- The original working directory (`HERMES_WORKDIR` file in the shadow repo).
|
||||
- Excluded paths such as:
|
||||
- `node_modules/`, `dist/`, `build/`
|
||||
- `.venv/`, `__pycache__/`, `*.pyc`
|
||||
- `.git/`, `.cache/`, `.pytest_cache/`, etc.
|
||||
|
||||
The agent creates **at most one checkpoint per directory per turn**, so long running sessions do not spam snapshots.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
user["User command\n(hermes, gateway)"]
|
||||
agent["AIAgent\n(run_agent.py)"]
|
||||
tools["File tools\n(write/patch)"]
|
||||
tools["File & terminal tools"]
|
||||
cpMgr["CheckpointManager"]
|
||||
shadowRepo["Shadow git repo\n~/.hermes/checkpoints/<hash>"]
|
||||
|
||||
|
|
@ -50,108 +55,128 @@ flowchart LR
|
|||
tools -->|"apply changes"| agent
|
||||
```
|
||||
|
||||
## Enabling Checkpoints
|
||||
## Configuration
|
||||
|
||||
Checkpoints are controlled by a simple on/off flag and a maximum snapshot count **per directory**:
|
||||
|
||||
- `checkpoints_enabled` – master switch
|
||||
- `checkpoint_max_snapshots` – soft cap on history depth per directory
|
||||
|
||||
You can configure these in `~/.hermes/config.yaml`:
|
||||
Checkpoints are enabled by default. Configure in `~/.hermes/config.yaml`:
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
checkpoints_enabled: true
|
||||
checkpoint_max_snapshots: 50
|
||||
checkpoints:
|
||||
enabled: true # master switch (default: true)
|
||||
max_snapshots: 50 # max checkpoints per directory
|
||||
```
|
||||
|
||||
Or via CLI flags (exact wiring may depend on your version of the CLI):
|
||||
To disable:
|
||||
|
||||
```bash
|
||||
hermes --checkpoints
|
||||
# or
|
||||
hermes chat --checkpoints
|
||||
```yaml
|
||||
checkpoints:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
When disabled, the Checkpoint Manager is a no‑op and never attempts git operations.
|
||||
|
||||
## Listing Checkpoints
|
||||
|
||||
Hermes exposes an interactive way to list checkpoints for the current working directory.
|
||||
From a CLI session:
|
||||
|
||||
From the CLI session where you are working on a project:
|
||||
|
||||
```bash
|
||||
# Ask Hermes to show checkpoints for the current directory
|
||||
```
|
||||
/rollback
|
||||
```
|
||||
|
||||
Hermes responds with a formatted list similar to:
|
||||
Hermes responds with a formatted list showing change statistics:
|
||||
|
||||
```text
|
||||
📸 Checkpoints for /path/to/project:
|
||||
|
||||
1. a1b2c3d 2026-03-13 10:24 auto: before apply_patch
|
||||
2. d4e5f6a 2026-03-13 10:15 pre-rollback snapshot (restoring to a1b2c3d0)
|
||||
1. 4270a8c 2026-03-16 04:36 before patch (1 file, +1/-0)
|
||||
2. eaf4c1f 2026-03-16 04:35 before write_file
|
||||
3. b3f9d2e 2026-03-16 04:34 before terminal: sed -i s/old/new/ config.py (1 file, +1/-1)
|
||||
|
||||
Use /rollback <number> to restore, e.g. /rollback 1
|
||||
/rollback <N> restore to checkpoint N
|
||||
/rollback diff <N> preview changes since checkpoint N
|
||||
/rollback <N> <file> restore a single file from checkpoint N
|
||||
```
|
||||
|
||||
Each entry shows:
|
||||
|
||||
- Short hash
|
||||
- Timestamp
|
||||
- Reason (commit message for the snapshot)
|
||||
- Reason (what triggered the snapshot)
|
||||
- Change summary (files changed, insertions/deletions)
|
||||
|
||||
## Previewing Changes with `/rollback diff`
|
||||
|
||||
Before committing to a restore, preview what has changed since a checkpoint:
|
||||
|
||||
```
|
||||
/rollback diff 1
|
||||
```
|
||||
|
||||
This shows a git diff stat summary followed by the actual diff:
|
||||
|
||||
```text
|
||||
test.py | 2 +-
|
||||
1 file changed, 1 insertion(+), 1 deletion(-)
|
||||
|
||||
diff --git a/test.py b/test.py
|
||||
--- a/test.py
|
||||
+++ b/test.py
|
||||
@@ -1 +1 @@
|
||||
-print('original content')
|
||||
+print('modified content')
|
||||
```
|
||||
|
||||
Long diffs are capped at 80 lines to avoid flooding the terminal.
|
||||
|
||||
## Restoring with `/rollback`
|
||||
|
||||
Once you have identified the snapshot you want to go back to, use `/rollback` with the number from the list:
|
||||
Restore to a checkpoint by number:
|
||||
|
||||
```bash
|
||||
# Restore to the most recent snapshot
|
||||
```
|
||||
/rollback 1
|
||||
```
|
||||
|
||||
Behind the scenes, Hermes:
|
||||
|
||||
1. Verifies the target commit exists in the shadow repo.
|
||||
2. Takes a **pre‑rollback snapshot** of the current state so you can “undo the undo” later.
|
||||
3. Runs `git checkout <hash> -- .` in the shadow repo, restoring tracked files in your working directory.
|
||||
2. Takes a **pre‑rollback snapshot** of the current state so you can "undo the undo" later.
|
||||
3. Restores tracked files in your working directory.
|
||||
4. **Undoes the last conversation turn** so the agent's context matches the restored filesystem state.
|
||||
|
||||
On success, Hermes responds with a short summary like:
|
||||
On success:
|
||||
|
||||
```text
|
||||
✅ Restored /path/to/project to a1b2c3d
|
||||
Reason: auto: before apply_patch
|
||||
✅ Restored to checkpoint 4270a8c5: before patch
|
||||
A pre-rollback snapshot was saved automatically.
|
||||
(^_^)b Undid 4 message(s). Removed: "Now update test.py to ..."
|
||||
4 message(s) remaining in history.
|
||||
Chat turn undone to match restored file state.
|
||||
```
|
||||
|
||||
If something goes wrong (missing commit, git error), you will see a clear error message and details will be logged.
|
||||
The conversation undo ensures the agent doesn't "remember" changes that have been rolled back, avoiding confusion on the next turn.
|
||||
|
||||
## Single-File Restore
|
||||
|
||||
Restore just one file from a checkpoint without affecting the rest of the directory:
|
||||
|
||||
```
|
||||
/rollback 1 src/broken_file.py
|
||||
```
|
||||
|
||||
This is useful when the agent made changes to multiple files but only one needs to be reverted.
|
||||
|
||||
## Safety and Performance Guards
|
||||
|
||||
To keep checkpointing safe and fast, Hermes applies several guardrails:
|
||||
|
||||
- **Git availability**
|
||||
- If `git` is not found on `PATH`, checkpoints are transparently disabled.
|
||||
- A debug log entry is emitted, but your session continues normally.
|
||||
- **Directory scope**
|
||||
- Hermes skips overly broad directories such as:
|
||||
- Root (`/`)
|
||||
- Your home directory (`$HOME`)
|
||||
- This prevents accidental snapshots of your entire filesystem.
|
||||
- **Repository size**
|
||||
- Before committing, Hermes performs a quick file count.
|
||||
- If the directory has more than a configured threshold (e.g. `50,000` files),
|
||||
checkpoints are skipped to avoid large git operations.
|
||||
- **No‑change snapshots**
|
||||
- If there are no changes since the last snapshot, the checkpoint is skipped
|
||||
instead of committing an empty diff.
|
||||
|
||||
All errors inside the Checkpoint Manager are treated as **non‑fatal**: they are logged at debug level and your tools continue to run.
|
||||
- **Git availability** — if `git` is not found on `PATH`, checkpoints are transparently disabled.
|
||||
- **Directory scope** — Hermes skips overly broad directories (root `/`, home `$HOME`).
|
||||
- **Repository size** — directories with more than 50,000 files are skipped to avoid slow git operations.
|
||||
- **No‑change snapshots** — if there are no changes since the last snapshot, the checkpoint is skipped.
|
||||
- **Non‑fatal errors** — all errors inside the Checkpoint Manager are logged at debug level; your tools continue to run.
|
||||
|
||||
## Where Checkpoints Live
|
||||
|
||||
By default, all shadow repos live under:
|
||||
All shadow repos live under:
|
||||
|
||||
```text
|
||||
~/.hermes/checkpoints/
|
||||
|
|
@ -160,21 +185,19 @@ By default, all shadow repos live under:
|
|||
└── ...
|
||||
```
|
||||
|
||||
Each `<hash>` is derived from the absolute path of the working directory. Inside each shadow repo you will find:
|
||||
Each `<hash>` is derived from the absolute path of the working directory. Inside each shadow repo you'll find:
|
||||
|
||||
- Standard git internals (`HEAD`, `refs/`, `objects/`)
|
||||
- An `info/exclude` file containing a curated ignore list
|
||||
- A `HERMES_WORKDIR` file pointing back to the original project root
|
||||
|
||||
You normally never need to touch these manually; they are documented here so advanced users understand how the safety net works.
|
||||
You normally never need to touch these manually.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Keep checkpoints enabled** for interactive development and refactors.
|
||||
- **Use `/rollback` instead of `git reset`** when you want to undo agent‑driven changes only.
|
||||
- **Combine with Git branches and worktrees** for maximum safety:
|
||||
- Keep each Hermes session in its own worktree/branch.
|
||||
- Let checkpoints act as an extra layer of protection on top.
|
||||
|
||||
For running multiple agents in parallel on the same repo without interfering with each other, see the dedicated guide on [Git worktrees](./git-worktrees.md).
|
||||
- **Leave checkpoints enabled** — they're on by default and have zero cost when no files are modified.
|
||||
- **Use `/rollback diff` before restoring** — preview what will change to pick the right checkpoint.
|
||||
- **Use `/rollback` instead of `git reset`** when you want to undo agent-driven changes only.
|
||||
- **Combine with Git worktrees** for maximum safety — keep each Hermes session in its own worktree/branch, with checkpoints as an extra layer.
|
||||
|
||||
For running multiple agents in parallel on the same repo, see the guide on [Git worktrees](./git-worktrees.md).
|
||||
|
|
|
|||
|
|
@ -50,6 +50,35 @@ hermes -w -q "Fix issue #123" # Single query in worktree
|
|||
|
||||
The welcome banner shows your model, terminal backend, working directory, available tools, and installed skills at a glance.
|
||||
|
||||
### Status Bar
|
||||
|
||||
A persistent status bar sits above the input area, updating in real time:
|
||||
|
||||
```
|
||||
⚕ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m
|
||||
```
|
||||
|
||||
| Element | Description |
|
||||
|---------|-------------|
|
||||
| Model name | Current model (truncated if longer than 26 chars) |
|
||||
| Token count | Context tokens used / max context window |
|
||||
| Context bar | Visual fill indicator with color-coded thresholds |
|
||||
| Cost | Estimated session cost (or `n/a` for unknown/zero-priced models) |
|
||||
| Duration | Elapsed session time |
|
||||
|
||||
The bar adapts to terminal width — full layout at ≥ 76 columns, compact at 52–75, minimal (model + duration only) below 52.
|
||||
|
||||
**Context color coding:**
|
||||
|
||||
| Color | Threshold | Meaning |
|
||||
|-------|-----------|---------|
|
||||
| Green | < 50% | Plenty of room |
|
||||
| Yellow | 50–80% | Getting full |
|
||||
| Orange | 80–95% | Approaching limit |
|
||||
| Red | ≥ 95% | Near overflow — consider `/compress` |
|
||||
|
||||
Use `/usage` for a detailed breakdown including per-category costs (input vs output tokens).
|
||||
|
||||
### Session Resume Display
|
||||
|
||||
When resuming a previous session (`hermes -c` or `hermes --resume <id>`), a "Previous Conversation" panel appears between the banner and the input prompt, showing a compact recap of the conversation history. See [Sessions — Conversation Recap on Resume](sessions.md#conversation-recap-on-resume) for details and configuration.
|
||||
|
|
|
|||
|
|
@ -441,6 +441,39 @@ Supported providers: `openrouter`, `nous`, `openai-codex`, `anthropic`, `zai`, `
|
|||
Fallback is configured exclusively through `config.yaml` — there are no environment variables for it. For full details on when it triggers, supported providers, and how it interacts with auxiliary tasks and delegation, see [Fallback Providers](/docs/user-guide/features/fallback-providers).
|
||||
:::
|
||||
|
||||
## Smart Model Routing
|
||||
|
||||
Optional cheap-vs-strong routing lets Hermes keep your main model for complex work while sending very short/simple turns to a cheaper model.
|
||||
|
||||
```yaml
|
||||
smart_model_routing:
|
||||
enabled: true
|
||||
max_simple_chars: 160
|
||||
max_simple_words: 28
|
||||
cheap_model:
|
||||
provider: openrouter
|
||||
model: google/gemini-2.5-flash
|
||||
# base_url: http://localhost:8000/v1 # optional custom endpoint
|
||||
# api_key_env: MY_CUSTOM_KEY # optional env var name for that endpoint's API key
|
||||
```
|
||||
|
||||
How it works:
|
||||
- If a turn is short, single-line, and does not look code/tool/debug heavy, Hermes may route it to `cheap_model`
|
||||
- If the turn looks complex, Hermes stays on your primary model/provider
|
||||
- If the cheap route cannot be resolved cleanly, Hermes falls back to the primary model automatically
|
||||
|
||||
This is intentionally conservative. It is meant for quick, low-stakes turns like:
|
||||
- short factual questions
|
||||
- quick rewrites
|
||||
- lightweight summaries
|
||||
|
||||
It will avoid routing prompts that look like:
|
||||
- coding/debugging work
|
||||
- tool-heavy requests
|
||||
- long or multi-line analysis asks
|
||||
|
||||
Use this when you want lower latency or cost without fully changing your default model.
|
||||
|
||||
## Terminal Backend Configuration
|
||||
|
||||
Configure which environment the agent uses for terminal commands:
|
||||
|
|
@ -453,7 +486,8 @@ terminal:
|
|||
|
||||
# Docker-specific settings
|
||||
docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
|
||||
docker_volumes: # Share host directories with the container
|
||||
docker_mount_cwd_to_workspace: false # SECURITY: off by default. Opt in to mount the launch cwd into /workspace.
|
||||
docker_volumes: # Additional explicit host mounts
|
||||
- "/home/user/projects:/workspace/projects"
|
||||
- "/home/user/data:/data:ro" # :ro for read-only
|
||||
|
||||
|
|
@ -520,41 +554,30 @@ This is useful for:
|
|||
|
||||
Can also be set via environment variable: `TERMINAL_DOCKER_VOLUMES='["/host:/container"]'` (JSON array).
|
||||
|
||||
### Docker Auto-Mount Current Directory
|
||||
### Optional: Mount the Launch Directory into `/workspace`
|
||||
|
||||
When using the Docker backend, Hermes **automatically mounts your current working directory** to `/workspace` inside the container. This means you can:
|
||||
Docker sandboxes stay isolated by default. Hermes does **not** pass your current host working directory into the container unless you explicitly opt in.
|
||||
|
||||
```bash
|
||||
cd ~/projects/my-app
|
||||
hermes
|
||||
# The agent can now see and edit files in ~/projects/my-app via /workspace
|
||||
Enable it in `config.yaml`:
|
||||
|
||||
```yaml
|
||||
terminal:
|
||||
backend: docker
|
||||
docker_mount_cwd_to_workspace: true
|
||||
```
|
||||
|
||||
No manual volume configuration needed — just `cd` to your project and run `hermes`.
|
||||
When enabled:
|
||||
- if you launch Hermes from `~/projects/my-app`, that host directory is bind-mounted to `/workspace`
|
||||
- the Docker backend starts in `/workspace`
|
||||
- file tools and terminal commands both see the same mounted project
|
||||
|
||||
**How it works:**
|
||||
- If you're in `/home/user/projects/my-app`, that directory is mounted to `/workspace`
|
||||
- The container's working directory is set to `/workspace`
|
||||
- Files you edit on the host are immediately visible to the agent, and vice versa
|
||||
When disabled, `/workspace` stays sandbox-owned unless you explicitly mount something via `docker_volumes`.
|
||||
|
||||
**Disabling auto-mount:**
|
||||
Security tradeoff:
|
||||
- `false` preserves the sandbox boundary
|
||||
- `true` gives the sandbox direct access to the directory you launched Hermes from
|
||||
|
||||
If you prefer the old behavior (empty `/workspace` with tmpfs or persistent sandbox), disable auto-mount:
|
||||
|
||||
```bash
|
||||
export TERMINAL_DOCKER_NO_AUTO_MOUNT=true
|
||||
```
|
||||
|
||||
**Precedence:**
|
||||
|
||||
Auto-mount is skipped when:
|
||||
1. `TERMINAL_DOCKER_NO_AUTO_MOUNT=true` is set
|
||||
2. You've explicitly configured a volume mount to `/workspace` in `docker_volumes`
|
||||
3. `container_persistent: true` is set (persistent sandbox mode uses its own `/workspace`)
|
||||
|
||||
:::tip
|
||||
Auto-mount is ideal for project-based work where you want the agent to operate on your actual files. For isolated sandboxing where the agent shouldn't access your filesystem, set `TERMINAL_DOCKER_NO_AUTO_MOUNT=true`.
|
||||
:::
|
||||
Use the opt-in only when you intentionally want the container to work on live host files.
|
||||
|
||||
### Persistent Shell
|
||||
|
||||
|
|
@ -843,6 +866,27 @@ display:
|
|||
| `all` | Every tool call with a short preview (default) |
|
||||
| `verbose` | Full args, results, and debug logs |
|
||||
|
||||
## Privacy
|
||||
|
||||
```yaml
|
||||
privacy:
|
||||
redact_pii: false # Strip PII from LLM context (gateway only)
|
||||
```
|
||||
|
||||
When `redact_pii` is `true`, the gateway redacts personally identifiable information from the system prompt before sending it to the LLM on supported platforms:
|
||||
|
||||
| Field | Treatment |
|
||||
|-------|-----------|
|
||||
| Phone numbers (user ID on WhatsApp/Signal) | Hashed to `user_<12-char-sha256>` |
|
||||
| User IDs | Hashed to `user_<12-char-sha256>` |
|
||||
| Chat IDs | Numeric portion hashed, platform prefix preserved (`telegram:<hash>`) |
|
||||
| Home channel IDs | Numeric portion hashed |
|
||||
| User names / usernames | **Not affected** (user-chosen, publicly visible) |
|
||||
|
||||
**Platform support:** Redaction applies to WhatsApp, Signal, and Telegram. Discord and Slack are excluded because their mention systems (`<@user_id>`) require the real ID in the LLM context.
|
||||
|
||||
Hashes are deterministic — the same user always maps to the same hash, so the model can still distinguish between users in group chats. Routing and delivery use the original values internally.
|
||||
|
||||
## Speech-to-Text (STT)
|
||||
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -1,97 +1,30 @@
|
|||
# Filesystem Checkpoints
|
||||
|
||||
Hermes can automatically snapshot your working directory before making file changes, giving you a safety net to roll back if something goes wrong.
|
||||
Hermes automatically snapshots your working directory before making file changes, giving you a safety net to roll back if something goes wrong. Checkpoints are **enabled by default**.
|
||||
|
||||
## How It Works
|
||||
## Quick Reference
|
||||
|
||||
When enabled, Hermes takes a **one-time snapshot** at the start of each conversation turn before the first file-modifying operation (`write_file` or `patch`). This creates a point-in-time backup you can restore to at any time.
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/rollback` | List all checkpoints with change stats |
|
||||
| `/rollback <N>` | Restore to checkpoint N (also undoes last chat turn) |
|
||||
| `/rollback diff <N>` | Preview diff between checkpoint N and current state |
|
||||
| `/rollback <N> <file>` | Restore a single file from checkpoint N |
|
||||
|
||||
Under the hood, checkpoints use a **shadow git repository** stored at `~/.hermes/checkpoints/`. This is completely separate from your project's git — no `.git` directory is created in your project, and your own git history is never touched.
|
||||
## What Triggers Checkpoints
|
||||
|
||||
## Enabling Checkpoints
|
||||
- **File tools** — `write_file` and `patch`
|
||||
- **Destructive terminal commands** — `rm`, `mv`, `sed -i`, output redirects (`>`), `git reset`/`clean`
|
||||
|
||||
### Per-session (CLI flag)
|
||||
|
||||
```bash
|
||||
hermes --checkpoints
|
||||
```
|
||||
|
||||
### Permanently (config.yaml)
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
checkpoints:
|
||||
enabled: true
|
||||
max_snapshots: 50 # max checkpoints per directory (default: 50)
|
||||
enabled: true # default: true
|
||||
max_snapshots: 50 # max checkpoints per directory
|
||||
```
|
||||
|
||||
## Rolling Back
|
||||
## Learn More
|
||||
|
||||
Use the `/rollback` slash command:
|
||||
|
||||
```
|
||||
/rollback # List all available checkpoints
|
||||
/rollback 1 # Restore to checkpoint #1 (most recent)
|
||||
/rollback 3 # Restore to checkpoint #3 (further back)
|
||||
/rollback abc1234 # Restore by git commit hash
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
📸 Checkpoints for /home/user/project:
|
||||
|
||||
1. abc1234 2026-03-10 14:22 before write_file
|
||||
2. def5678 2026-03-10 14:15 before patch
|
||||
3. ghi9012 2026-03-10 14:08 before write_file
|
||||
|
||||
Use /rollback <number> to restore, e.g. /rollback 1
|
||||
```
|
||||
|
||||
When you restore, Hermes automatically takes a **pre-rollback snapshot** first — so you can always undo your undo.
|
||||
|
||||
## What Gets Checkpointed
|
||||
|
||||
Checkpoints capture the entire working directory (the project root), excluding common large/sensitive patterns:
|
||||
|
||||
- `node_modules/`, `dist/`, `build/`
|
||||
- `.env`, `.env.*`
|
||||
- `__pycache__/`, `*.pyc`
|
||||
- `.venv/`, `venv/`
|
||||
- `.git/`
|
||||
- `.DS_Store`, `*.log`
|
||||
|
||||
## Performance
|
||||
|
||||
Checkpoints are designed to be lightweight:
|
||||
|
||||
- **Once per turn** — only the first file operation triggers a snapshot, not every write
|
||||
- **Skips large directories** — directories with >50,000 files are skipped automatically
|
||||
- **Skips when nothing changed** — if no files were modified since the last checkpoint, no commit is created
|
||||
- **Non-blocking** — if a checkpoint fails for any reason, the file operation proceeds normally
|
||||
|
||||
## How It Determines the Project Root
|
||||
|
||||
When you write to a file like `src/components/Button.tsx`, Hermes walks up the directory tree looking for project markers (`.git`, `pyproject.toml`, `package.json`, `Cargo.toml`, etc.) to find the project root. This ensures the entire project is checkpointed, not just the file's parent directory.
|
||||
|
||||
## Platforms
|
||||
|
||||
Checkpoints work on both:
|
||||
- **CLI** — uses your current working directory
|
||||
- **Gateway** (Telegram, Discord, etc.) — uses `MESSAGING_CWD`
|
||||
|
||||
The `/rollback` command is available on all platforms.
|
||||
|
||||
## FAQ
|
||||
|
||||
**Does this conflict with my project's git?**
|
||||
No. Checkpoints use a completely separate shadow git repository via `GIT_DIR` environment variables. Your project's `.git/` is never touched.
|
||||
|
||||
**How much disk space do checkpoints use?**
|
||||
Git is very efficient at storing diffs. For most projects, checkpoint data is negligible. Old checkpoints are pruned when `max_snapshots` is exceeded.
|
||||
|
||||
**Can I checkpoint without git installed?**
|
||||
No — git must be available on your PATH. If it's not installed, checkpoints silently disable.
|
||||
|
||||
**Can I roll back across sessions?**
|
||||
Yes! Checkpoints persist in `~/.hermes/checkpoints/` and survive across sessions. You can roll back to a checkpoint from yesterday.
|
||||
For the full guide — how shadow repos work, diff previews, file-level restore, conversation undo, safety guards, and best practices — see **[Checkpoints and /rollback](../checkpoints-and-rollback.md)**.
|
||||
|
|
|
|||
62
website/docs/user-guide/features/plugins.md
Normal file
62
website/docs/user-guide/features/plugins.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
sidebar_position: 20
|
||||
---
|
||||
|
||||
# Plugins
|
||||
|
||||
Hermes has a plugin system for adding custom tools, hooks, 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.
|
||||
|
||||
## What plugins can do
|
||||
|
||||
| Capability | How |
|
||||
|-----------|-----|
|
||||
| Add tools | `ctx.register_tool(name, schema, handler)` |
|
||||
| Add hooks | `ctx.register_hook("post_tool_call", callback)` |
|
||||
| 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 |
|
||||
| pip | `hermes_agent.plugins` entry_points | Distributed packages |
|
||||
|
||||
## Available hooks
|
||||
|
||||
| Hook | Fires when |
|
||||
|------|-----------|
|
||||
| `pre_tool_call` | Before any tool executes |
|
||||
| `post_tool_call` | After any tool returns |
|
||||
| `pre_llm_call` | Before LLM API request |
|
||||
| `post_llm_call` | After LLM API response |
|
||||
| `on_session_start` | Session begins |
|
||||
| `on_session_end` | Session ends |
|
||||
|
||||
## 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.
|
||||
|
|
@ -118,6 +118,18 @@ Replies are sent via SMTP with proper email threading:
|
|||
|
||||
The agent can send file attachments in replies. Include `MEDIA:/path/to/file` in the response and the file is attached to the outgoing email.
|
||||
|
||||
### Skipping Attachments
|
||||
|
||||
To ignore all incoming attachments (for malware protection or bandwidth savings), add to your `config.yaml`:
|
||||
|
||||
```yaml
|
||||
platforms:
|
||||
email:
|
||||
skip_attachments: true
|
||||
```
|
||||
|
||||
When enabled, attachment and inline parts are skipped before payload decoding. The email body text is still processed normally.
|
||||
|
||||
---
|
||||
|
||||
## Access Control
|
||||
|
|
|
|||
|
|
@ -244,10 +244,10 @@ Background tasks on messaging platforms are fire-and-forget — you don't need t
|
|||
|
||||
```bash
|
||||
hermes gateway install # Install as user service
|
||||
systemctl --user start hermes-gateway
|
||||
systemctl --user stop hermes-gateway
|
||||
systemctl --user status hermes-gateway
|
||||
journalctl --user -u hermes-gateway -f
|
||||
hermes gateway start # Start the service
|
||||
hermes gateway stop # Stop the service
|
||||
hermes gateway status # Check status
|
||||
journalctl --user -u hermes-gateway -f # View logs
|
||||
|
||||
# Enable lingering (keeps running after logout)
|
||||
sudo loginctl enable-linger $USER
|
||||
|
|
@ -263,6 +263,10 @@ Use the user service on laptops and dev boxes. Use the system service on VPS or
|
|||
|
||||
Avoid keeping both the user and system gateway units installed at once unless you really mean to. Hermes will warn if it detects both because start/stop/status behavior gets ambiguous.
|
||||
|
||||
:::info Multiple installations
|
||||
If you run multiple Hermes installations on the same machine (with different `HERMES_HOME` directories), each gets its own systemd service name. The default `~/.hermes` uses `hermes-gateway`; other installations use `hermes-gateway-<hash>`. The `hermes gateway` commands automatically target the correct service for your current `HERMES_HOME`.
|
||||
:::
|
||||
|
||||
### macOS (launchd)
|
||||
|
||||
```bash
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue