Plugins

MindRoom plugins add tools and can optionally ship skills. Plugins are loaded from paths listed in config.yaml.

Plugin structure

A plugin is a directory containing mindroom.plugin.json:

my-plugin/
├── mindroom.plugin.json
├── tools.py
└── skills/
    └── my-skill/
        └── SKILL.md

Manifest format

{
  "name": "my-plugin",
  "tools_module": "tools.py",
  "skills": ["skills"]
}

Unknown fields are ignored.

Configure plugins

Add plugin paths to config.yaml:

plugins:
  - ./plugins/my-plugin
  - python:my_skill_pack

Paths may be:

• Absolute paths
• Paths relative to config.yaml
• Python package specs (see below)

Python package plugins

MindRoom can resolve plugins from installed Python packages:

plugins:
  - my_skill_pack
  - python:my_skill_pack
  - pkg:my_skill_pack:plugins/demo
  - module:my_skill_pack:plugins/demo

Rules:

• A bare package name is allowed if it contains no slashes.
• python:, pkg:, and module: are explicit prefixes.
• :sub/path points to a subdirectory inside the package.

MindRoom resolves the package location and looks for mindroom.plugin.json in that directory.

Tools module example

from __future__ import annotations

from typing import TYPE_CHECKING

from mindroom.tools_metadata import (
    SetupType,
    ToolCategory,
    ToolStatus,
    register_tool_with_metadata,
)

if TYPE_CHECKING:
    from agno.tools import Toolkit


@register_tool_with_metadata(
    name="greeter",
    display_name="Greeter",
    description="A simple greeting tool",
    category=ToolCategory.DEVELOPMENT,
    status=ToolStatus.AVAILABLE,
    setup_type=SetupType.NONE,
)
def greeter_tools() -> type[Toolkit]:
    from agno.tools import Toolkit

    class GreeterTools(Toolkit):
        """A simple greeting toolkit."""

        def __init__(self) -> None:
            super().__init__(name="greeter", tools=[self.greet])

        def greet(self, name: str) -> str:
            """Greet someone by name."""
            return f"Hello, {name}!"

    return GreeterTools

The factory function (decorated with @register_tool_with_metadata) must return the class, not an instance. MindRoom instantiates the class when building agents.

All decorator arguments are keyword-only. Required fields:

• name: Tool identifier
• display_name: Human-readable name
• description: Brief description
• category: A ToolCategory enum value

Common optional fields:

• status: ToolStatus.AVAILABLE (default), COMING_SOON, or REQUIRES_CONFIG
• setup_type: SetupType.NONE (default), API_KEY, OAUTH, or SPECIAL
• config_fields: List of ConfigField objects for configuration
• dependencies: List of required pip packages
• docs_url: Link to documentation

Plugin skills

List skill directories in the manifest skills array. Those directories are added to the skill search roots.

Reloading plugins

Plugin manifests and tools modules are cached by mtime. Changes are picked up the next time MindRoom reloads the tool registry (for example, on startup or config reload).

Security notes

Plugins execute code in-process. Only install plugins you trust.