Built-in Plugins — Ready-to-Use Enhancements

Think of plugins like phone apps for your AI assistant — you don’t rebuild the phone, you just add a small app that does one thing really well.

What Are Hermes Plugins?

Hermes plugins are small folders you drop into a special directory. Each folder contains a few files that tell Hermes: “Hey, here’s a new tool the AI can use, and here’s what to do when it’s called.” You don’t touch the core code. It’s like adding a new button to your remote control without opening the TV.

The Magic Folder

All plugins live here:

~/.hermes/plugins/

Inside, each plugin is its own folder. A minimal one looks like this:

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # basic info about the plugin
├── __init__.py      # where you wire things together
├── schemas.py       # what the AI "sees" (descriptions)
└── tools.py         # what actually runs when called

You don’t need all those files for a simple plugin — just plugin.yaml and __init__.py will do.

Your First Plugin in 2 Minutes

Here’s a complete example that adds a hello_world tool and logs every tool call.

File 1: ~/.hermes/plugins/hello-world/plugin.yaml

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

File 2: ~/.hermes/plugins/hello-world/__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}!"})

    # Wire them together
    ctx.register_tool(
        name="hello_world",
        toolset="hello_world",
        schema=schema,
        handler=handle_hello,
    )

    # Bonus: log every tool call
    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)

Drop both files into ~/.hermes/plugins/hello-world/, restart Hermes, and the AI can immediately call hello_world. The hook prints a log line after every tool call — great for debugging.

What Else Can Plugins Do?

Plugins aren’t just for tools. You can also:

• Add hooks — run code before or after events (like the logging example above)
• Add slash commands — create custom /commands in the CLI, like /deploy or /summarize

One Important Warning

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

export HERMES_ENABLE_PROJECT_PLUGINS=true

Always check what a plugin does before enabling it — it’s like installing software from the internet.

Summary & Practical Tip

Plugins let you extend Hermes without touching core code. Start with the hello_world example, then modify the schema and handler to do something useful for your workflow.

Tip: Keep your plugin’s description field in the schema clear and specific — that’s what the AI reads to decide when to use your tool. A vague description means the AI won’t know when to call it.