Plugin Development Guide

Extend Boring's capabilities with custom Python tools.

---

🛠️ Overview

Boring features a dynamic plugin system that allows you to register custom Python functions as AI-accessible tools. Plugins can be project-specific or global.

Plugin Locations

1. Project-Local: {project_root}/.boring_plugins/
2. User-Global: ~/.boring/plugins/

---

📝 Creating a Plugin

To create a plugin, define a Python function and decorate it with @plugin.

Example: my_tool_plugin.py

from boring.plugins.loader import plugin

@plugin(
    name="my_custom_linter",
    description="Custom linting rules for specific business logic",
    version="1.0.0",
    author="Vibe Coder",
    tags=["lint", "custom"]
)
def my_custom_linter(file_path: str) -> dict:
    """
    Analyzes a file for custom patterns.
    """
    # Your logic here
    if "todo" in open(file_path).read().lower():
        return {"passed": False, "issues": ["Found lingering TODOs"]}

    return {"passed": True, "issues": []}

---

🚀 Loading and Hot-Reload

• Discovery: Any .py file or files ending in _plugin.py in the search paths are automatically discovered.
• Hot-Reload: Boring monitors plugin files. If you edit a plugin while the loop is running, it will automatically reload the new logic for the next iteration.

---

🔍 Using Plugins

Once loaded, your plugin becomes available to the AI agent just like built-in tools. The agent will discover it via semantic search or tool listing.

To list currently loaded plugins:

boring list-plugins

---

🛡️ Security & Safety

Plugins, especially those generated via boring_synth_tool, are subject to strict security constraints:

1. AST-based Sandbox: All synthesized tools are validated using a SynthesizedToolValidator.
2. Forbidden Operations: To prevent destructive actions, the sandbox blocks:
   • Forbidden Imports: os, sys, subprocess, shutil, socket
   • Forbidden Functions: exec(), eval(), open(), compile()
3. Shadow Mode Binding: All plugin executions are monitored by Shadow Mode if enabled, providing a secondary defense against unintended file modifications.

---

💡 Best Practices

1. Type Hints: Always use type hints for arguments to help the LLM understand the input.
2. Docstrings: Provide clear, descriptive docstrings as they are used by the AI to decide when to call the tool.
3. Return Format: Return structured data (dict) rather than just strings for better agent processing.