Request: Plugin development guide + working example for custom tools/plugins

[edwardcodelab]

Hi CheetahClaws team,
I'm trying to build a simple custom plugin/tool for the system but I'm unable to get it working. Could you please provide:

An official plugin development guide (how to structure plugins, register tools, how the auto-call / trigger mechanism works, etc.)
A complete working minimal example of a plugin that registers a tool.

What I'm trying to achieve
I want the LLM to automatically call a tool and reply with a cat emoji 🐱 whenever the user prompt contains the word "sample".
My current attempt which is not working:

"""
LLM can automatically call to reply with a cat emoji 🐱
when the user prompt contains the word "sample".
"""
from tool_registry import ToolDef
from typing import Dict, Any

def _sample_cat_tool(params: Dict[str, Any], config: Dict[str, Any]) -> str:
    cat_emoji = "🐱"
   
    reason = params.get("reason", "user mentioned 'sample' in prompt")
   
    response = (
        f"{cat_emoji} Meow! 'sample' was detected in ({reason})! "
        f"{cat_emoji} {cat_emoji} {cat_emoji} !"
    )
    return response

TOOL_DEFS = [
    ToolDef(
        name="SampleCatEmoji",
        schema={
            "name": "SampleCatEmoji",
            "description": (
                "Automatically respond with a cute cat emoji 🐱 whenever the user's prompt "
                "contains the word 'sample'."
            ),
            "input_schema": {
                "type": "object",
                "properties": {
                    "reason": {
                        "type": "string",
                        "description": "Explanation why the tool was triggered.",
                        "default": "prompt contains 'sample'"
                    }
                },
                "required": []
            },
        },
        func=_sample_cat_tool,
        read_only=True,
        concurrent_safe=True,
    ),
]

I placed this file in the plugins folder (and also tried /plugin install sample@..... path ) but the tool is never called automatically.

a plugin example or official plugin development guide would be greatly appreciated.

Thanks!

[chauncygu]

Hi @edwardcodelab, sorry the docs didn't surface easily.

A plugin authoring guide and a working example do exist in the repo:

• Guide: docs/guides/plugin-authoring.md (~485 lines, covers manifest fields, ToolDef API, slash commands, skills, MCP servers, install/distribution)
• Working template: examples/example-plugin/ — directory with plugin.json, tools.py, cmd.py, skills/, README.md

Why your attempt didn't load

The loader (plugin/loader.py) only registers tools that come from a plugin directory with a manifest declaring which Python module exports TOOL_DEFS. Dropping a single .py file under plugins/ is silently ignored — there's no manifest, so the loader has nothing to import.

Minimal fix for your cat-emoji example

Create a directory under one of these scopes:

• ~/.cheetahclaws/plugins/<name>/ — user scope (recommended)
• .cheetahclaws/plugins/<name>/ — project scope (in your CWD)
• $CHEETAHCLAWS_PLUGIN_PATH/<name>/ — external

~/.cheetahclaws/plugins/sample-cat/
├── plugin.json
└── tools.py

plugin.json:

{
  "name": "sample-cat",
  "version": "0.1.0",
  "description": "Reply with a cat emoji when the prompt mentions 'sample'.",
  "tools": ["tools"]
}

tools.py: your existing code is fine — keep TOOL_DEFS = [ToolDef(...)] as-is.

Restart cheetahclaws (the loader runs at startup), then verify:

/plugin           # should list "sample-cat"
/tools            # should show "SampleCatEmoji" registered

About /plugin install <path>

The syntax is name@source, where source is a git URL or a local directory path:

/plugin install sample-cat@/abs/path/to/sample-cat
/plugin install my-plugin@https://github.com/you/cheetahclaws-my-plugin

You wrote /plugin install sample@..... path — the name@ prefix is required, and the path must be a directory containing plugin.json. Pointing at a bare .py file won't work.

On "auto-call when prompt contains 'sample'"

CheetahClaws doesn't pattern-match user input to fire tools — that's not how tool-calling works. Tools are invoked when the LLM decides to call them based on the tool's description. Your description ("Automatically respond with a cute cat emoji 🐱 whenever the user's prompt contains the word 'sample'.") is good and a Claude/GPT-class model will follow it reliably. Weaker local models may ignore it — if you're on Qwen/Llama, you might also need a system-prompt nudge or a more imperative description.

If you're still stuck after the above, please share:

1. Output of /plugin list and /tools after restart
2. The contents of ~/.cheetahclaws/plugins/<name>/plugin.json
3. Which model you're running (/model)

Happy to add a cat-sample walkthrough to the existing guide if it'd help — let me know.