Plugin Best Practices

Plugin Best Practices

Full guide at: docs/plugins/best-practices.md

Core Principles

1. Single responsibility — one plugin, one job
2. Fail gracefully — return failure results, never throw from execute
3. Validate inputs — check params at the top of every tool
4. Respect timeouts — track durationMs accurately
5. Declare minimal permissions — only request what you use
6. Handle cleanup — always clean up in onUnload

ESM Specific

• Use TypeScript for type safety
• Avoid global state — use PluginContext.state or lazy init
• Handle cleanup in onUnload (clear intervals, close connections)

MCP Specific

• Handle process lifecycle (SIGTERM/SIGINT)
• Minimize startup time — defer expensive setup
• Stream large results where possible

WASM Specific

• Optimize for size (opt-level=s, lto=true, strip=true)
• Use simple types — JSON for complex data
• Test outside CortexPrism first (wasmtime run plugin.wasm)

Testing

cortex plugins install ./my-plugin
cortex plugins enable my-plugin
cortex plugins list
cortex chat  # test in a chat session

What to Avoid

• Hardcoded secrets — use ctx.config or env vars
• Synchronous blocking — all execute functions must be async
• Overly broad permissions — request minimum required
• Crashing the host — never throw from tool execution
• Silent failures — log errors and return meaningful messages
• Undocumented config keys — declare all settings in ui.settings

See Also

• Developing Plugins — Full development guide
• Publishing Plugins — Submit to marketplace