Plugin System

Plugin System

CortexPrism supports plugins that extend its capabilities with new tools, UI panels, CLI commands, LLM providers, and middleware.

Plugin Types

Kind	Description	Best For
ESM	JavaScript/TypeScript modules loaded via import()	Most plugins — tools, UI, providers, middleware
MCP	Model Context Protocol servers (JSON-RPC)	Wrapping existing MCP servers as tools
WASM	WebAssembly modules (any language → WASM)	Performance-critical or multi-language plugins

Quick Start

# Install from marketplace
cortex marketplace install plugins/slack-bot

# Install from URL
cortex plugins install https://example.com/my-plugin/manifest.json

# Install from local manifest
cortex plugins install ./my-plugin/manifest.json

# List installed plugins
cortex plugins list

# Manage plugins
cortex plugins enable my-plugin
cortex plugins disable my-plugin
cortex plugins update my-plugin
cortex plugins update --all
cortex plugins verify my-plugin
cortex plugins permissions my-plugin
cortex plugins remove my-plugin

Plugin Lifecycle

DISCOVERED → INSTALLED → LOADING → ACTIVE
                                      ↓
                                  UNLOADING → REMOVED

Lifecycle hooks:

• onInstall — plugin first installed
• onLoad — module imported into memory
• onActivate — tools registered, providers bound
• onDeactivate — plugin begins disabling
• onUnload — module unloaded from memory
• onUninstall — database row deleted, files cleaned

Manifest Structure

Every plugin requires a manifest.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "An example plugin",
  "kind": "esm",
  "entryPoint": "./mod.ts",
  "runtime": "deno",
  "capabilities": ["tools", "network:fetch"],
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "params": [
        { "name": "city", "type": "string", "description": "City name", "required": true }
      ]
    }
  ]
}

Extension Points

Capability	Description
tools	Register tools in the global agent tool registry
cli:commands	Add cortex <name> subcommands
ui:panel	Add a Web UI panel/tab
ui:widget	Add a dashboard widget
config:schema	Extend config schema with new settings
config:provider	Register LLM provider factories
memory:store	Custom memory backend
memory:embedder	Custom embedding provider
events:listener	Subscribe to the event bus
middleware:pre	Pre-execution middleware
middleware:post	Post-execution middleware

Trust Levels

Level	Sandbox	Permissions
untrusted	Worker sandbox	Limited to declared permissions
signed	Worker sandbox	Broader permissions based on signature
trusted	In-process	Full declared permissions

PluginContext API

Every lifecycle hook and tool receives a PluginContext:

interface PluginContext {
  pluginId: string;           // Plugin name
  pluginDir: string;          // Plugin directory path
  state: PluginStateStore;    // Persistent key-value store
  config: PluginConfigStore;  // Typed config access
  logger: PluginLogger;       // Scoped logger
  host: HostApi;              // Register/unregister tools
}

Event Subscriptions

Plugins can subscribe to system events:

Event	When
session:start	New agent session begins
session:end	Agent session ends
tool:pre-execute	Before any tool executes
tool:post-execute	After any tool executes
llm:pre-call	Before an LLM API call
llm:post-call	After an LLM API call
agent:turn-start	Start of an agent reasoning turn
agent:turn-end	End of an agent reasoning turn

See Also

• Developing Plugins — Full development guide
• Manifest Reference — Complete manifest schema
• Plugin Best Practices — Design principles
• Publishing Plugins — Submit to the marketplace