Plugin System

The plugin system allows extending Octipus’s capabilities by dropping plugins into the extensions/ directory. Each plugin provides tools that are automatically registered and available to agents.

Plugin Structure

extensions/
  my-plugin/
    plugin.json    # Manifest (required)
    index.ts       # Entry file (required)

Manifest (plugin.json)

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Does something useful",
  "author": "Your Name",
  "main": "index.ts",
  "tools": [
    {
      "name": "my_tool",
      "description": "Does a specific thing",
      "parameters": {
        "input": { "type": "string", "description": "The input", "required": true }
      }
    }
  ]
}

Entry File (index.ts)

export default {
  name: 'my-plugin',

  async initialize(context) {
    context.logger.info('Plugin loaded');
  },

  tools: {
    async my_tool(args) {
      return { result: `Processed: ${args.input}` };
    },
  },

  async shutdown() {},
};

Loading

1. At startup, the loader scans extensions/ for directories with plugin.json
2. Manifests are validated (name, version, description, main, tools)
3. Entry files are dynamically imported
4. initialize() is called with a logger context
5. Each plugin is wrapped as a BaseTool and registered with the tool registry
6. Plugin tools become available to agents as plugin-<name>__<tool_name>

API

Method	Path	Description
GET	/api/plugins	List all loaded plugins
GET	/api/plugins/:name	Plugin details
POST	/api/plugins/:name/reload	Hot-reload from disk

Skill Sharing

Skills can be exported and imported for sharing between instances:

Method	Path	Description
GET	/api/skills/export	Export skills as JSON or markdown
GET	/api/skills/:id/export	Export single skill
POST	/api/skills/import	Import skills with conflict handling

Markdown format uses YAML frontmatter for metadata and structured sections for principles, best practices, and anti-patterns.