Plugin System — Endless Extensions

Think of plugins like phone apps for your AI assistant — you don’t rebuild the phone to get a new camera filter; you just install an app. Hermes works the same way: drop in a folder, restart, and your AI gains new powers instantly.

What Is a Plugin, Really?

A plugin is a small package of files that tells Hermes, “Hey, I have a new tool for you to use.” You don’t need to touch the core code. It’s perfect for adding custom tools for yourself, your team, or a single project.

The Magic Folder

All your plugins live in one place:

~/.hermes/plugins/

Inside that folder, each plugin gets its own subfolder. Here’s the structure:

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # manifest (name, version, description)
├── __init__.py      # register() — wires everything together
├── schemas.py       # tool schemas (what the AI sees)
└── tools.py         # tool handlers (what runs when called)

Your First Plugin in 3 Steps

Let’s build a hello_world tool. It’s simpler than it looks.

Step 1: Create the manifest — plugin.yaml

name: hello-world
version: "1.0"
description: A minimal example plugin

Step 2: Write the logic — __init__.py

import json

def register(ctx):
    # Define what the AI sees
    schema = {
        "name": "hello_world",
        "description": "Returns a friendly greeting for the given name.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "Name to greet"}
            },
            "required": ["name"],
        },
    }

    # Define what actually runs
    def handle_hello(params, **kwargs):
        name = params.get("name", "World")
        return json.dumps({"success": True, "greeting": f"Hello, {name}!"})

    # Register the tool
    ctx.register_tool(name="hello_world", toolset="hello_world",
                      schema=schema, handler=handle_hello)

Step 3: Drop it in and restart

Put both files in ~/.hermes/plugins/hello-world/, restart Hermes, and your AI can call hello_world immediately.

What Else Can Plugins Do?

The register(ctx) function gives you superpowers:

Capability	How
Add tools	ctx.register_tool(...)
Add hooks	ctx.register_hook("post_tool_call", callback)
Add slash commands	ctx.register_command(name, handler, description)

For example, you can log every tool call with a hook:

def on_tool_call(tool_name, params, result):
    print(f"[hello-world] tool called: {tool_name}")

ctx.register_hook("post_tool_call", on_tool_call)

A Word of Caution

Project-local plugins (in ./.hermes/plugins/) are disabled by default for safety. Only enable them for trusted repositories by setting:

export HERMES_ENABLE_PROJECT_PLUGINS=true

Summary & Pro Tip

Plugins let you extend Hermes without touching core code — just a folder, a manifest, and a Python file. Start with the hello_world example, then replace the greeting logic with your own API calls or database queries.

Practical tip: Always keep your schema description clear and specific. The AI reads that text to decide when to use your tool — write it like you’re explaining it to a smart friend who’s never seen it before.