Skip to content

Plugin Authoring

Jump to bottom
idapixl edited this page Mar 15, 2026 · 1 revision

Plugin Authoring

Build custom plugins to extend cortex-engine with new tools.

Structure

tools-<name>/
├── src/
│   └── index.ts        # Plugin definition and tool handlers
├── package.json        # cortex-engine as peerDependency
├── tsconfig.json
├── README.md
└── tests/
    └── index.test.ts

Minimal Example

// src/index.ts
import type { CortexPlugin, CortexInstance } from 'cortex-engine';

export const myPlugin: CortexPlugin = {
  name: 'my-plugin',
  version: '0.1.0',
  tools: [
    {
      name: 'my_custom_tool',
      description: 'A tool that does something useful for the agent',
      parameters: {
        type: 'object',
        properties: {
          input: {
            type: 'string',
            description: 'The input to process',
          },
        },
        required: ['input'],
      },
      handler: async (cortex: CortexInstance, params: { input: string }) => {
        // You have full access to the cortex instance
        const related = await cortex.query(params.input);

        // Process and return
        return {
          processed: true,
          related_count: related.length,
          summary: `Found ${related.length} related memories`,
        };
      },
    },
  ],
};

package.json

{
  "name": "@fozikio/tools-my-plugin",
  "version": "0.1.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "peerDependencies": {
    "cortex-engine": ">=0.4.0"
  },
  "scripts": {
    "build": "tsc",
    "test": "vitest"
  }
}

Using Firestore

Plugins access Firestore through the cortex instance:

handler: async (cortex, params) => {
  const db = cortex.firestore;

  // Read from a custom collection
  const doc = await db.collection('my_collection').doc(params.id).get();

  // Write
  await db.collection('my_collection').add({
    content: params.input,
    created_at: new Date(),
  });

  return { success: true };
}

Conventions

Follow these patterns for consistency with the official plugin ecosystem:

  1. Naming: tools-<name> for the repo, @fozikio/tools-<name> for the npm package
  2. Tool names: Use snake_case — e.g., thread_create, journal_write
  3. Return values: Always return an object, never a bare string or number
  4. Descriptions: Write tool descriptions for LLMs — be clear about when to use the tool and what it returns
  5. Error handling: Throw descriptive errors, don't return error objects

Official Plugins

Reference implementations to study:

Plugin Tools Complexity
tools-vitals 2 Simple — good starting point
tools-journal 2 Simple — read/write pattern
tools-threads 4 Medium — CRUD with state
tools-graph 4 Advanced — graph analysis
tools-reasoning 6 Advanced — multi-step cognition

Publishing

npm run build
npm publish --access public

Then tell people to install it:

npm install @fozikio/tools-my-plugin

And register it:

import { CortexEngine } from 'cortex-engine';
import { myPlugin } from '@fozikio/tools-my-plugin';

const cortex = new CortexEngine({
  projectId: 'your-project',
  plugins: [myPlugin],
});

Clone this wiki locally