Catboi Plugin Template

A template for creating plugin tools that can be dropped into the plugins/ folder and loaded automatically at runtime.

Quick Start

1. Create your tool — copy ExampleTool.kt and modify it:

   • Change the class name, name, and toolDefinition to match your tool.
   • Implement the execute method with your logic.
   • You have full access to ToolContext (Bluesky client, memory DB, Ollama client, etc.).

2. Build the plugin JAR:

   ./gradlew :plugin-template:jar
   

   The JAR is output to plugin-template/build/libs/.

3. Deploy to the plugins folder:

   ./gradlew :plugin-template:deployPlugin
   

   This builds the JAR and copies it directly into the root plugins/ directory.

4. Restart catboi — your tool is discovered automatically.

Using as a Standalone Project

To use this template outside the catboi monorepo:

1. Copy the plugin-template/ directory to a new location.
2. Replace the compileOnly(project(":agent")) and compileOnly(project(":ollama")) dependencies in build.gradle.kts with published artifacts or local JAR references:

   dependencies {
       compileOnly(files("/path/to/catboi/agent/build/libs/agent.jar"))
       compileOnly(files("/path/to/catboi/ollama/build/libs/ollama.jar"))
       compileOnly("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0")
   }
   

3. Build with ./gradlew jar and drop the resulting JAR into catboi's plugins/ folder.

Key Interfaces

AgentTool

Every plugin tool must implement AgentTool:

interface AgentTool {
    val name: String              // Unique tool name (used for dispatching)
    val toolDefinition: Tool      // Ollama tool definition (name, description, parameters)
    fun isAvailable(): Boolean    // Return false to conditionally disable the tool
    suspend fun execute(args: Map<String, JsonElement>, context: ToolContext): String
}

ToolContext

The context parameter gives your tool access to:

Field	Description
blueskyClient	Bluesky client for posting/replying
memory	Multi-table vector database for memory operations
ollamaClient	Ollama client for AI operations (embeddings, etc.)
llmBackend	LLM backend for chat operations
model	Name of the main AI model
embeddingModel	Name of the embedding model
agentUserId	The bot's own Bluesky DID
interactingUserId	The current user's ID

Important Notes

• Dependencies on agent, ollama, and kotlinx-serialization-json are compileOnly — they are provided at runtime by the main catboi application. Do not bundle them in your plugin JAR.
• If your plugin needs additional libraries (e.g., an HTTP client), add them as implementation dependencies — they will be bundled into the fat JAR automatically.
• Tool classes must have a no-argument constructor so they can be instantiated via reflection.