Skip to main content
profClaw’s plugin system lets you add new capabilities without forking the core. Plugins can provide AI tools (for function calling), search providers, skills, and chat channel integrations.

​
Plugin Categories

CategoryWhat it adds
toolNew tools available to the AI during execution
searchA new web or knowledge search backend
integrationExternal service connection (ticket systems, APIs)
modelA custom AI model provider

​
Architecture

Plugin Package (npm)
    |
    v
pluginRegistry.register(id, factory)
    |
    v
pluginRegistry.create(config)  --> PluginInstance
    |
    v
Tool Router / Search Router use the plugin at runtime
The registry (src/plugins/registry.ts) holds factories keyed by plugin ID. Configuration is stored in the database and loaded on startup. Plugins run in an optional sandbox (src/plugins/sandbox.ts) for untrusted code.

​
Plugin Metadata

Every plugin declares metadata that drives the settings UI and ClawHub listing: 
export interface PluginMetadata {
  id: string;
  name: string;
  description: string;
  category: PluginCategory;
  icon?: string;           // Lucide icon name
  version: string;
  author?: string;
  homepage?: string;
  pricing?: {
    type: 'free' | 'paid' | 'freemium' | 'credit-based';
    costPer1k?: number;
    freeQuota?: number;
  };
  rateLimit?: {
    requestsPerSecond?: number;
    requestsPerMinute?: number;
    requestsPerDay?: number;
  };
}

​
Plugin Lifecycle

1

Install

Install the plugin package via npm/pnpm or download from ClawHub:
profclaw plugins install @profclaw/plugin-jira-search
2

Register

The plugin factory is registered with pluginRegistry.register(id, factory) on server startup.
3

Configure

The user provides credentials and settings via the settings UI. The UI is auto-generated from the plugin’s PluginSettingsSchema.
4

Load

The onLoad(config) lifecycle hook is called with the saved configuration. Use this to validate credentials and initialize connections.
5

Execute

Tools or search functions are called at runtime by the execution engine. Results are returned to the AI model.
6

Health check

healthCheck() is polled periodically and surfaced in the settings dashboard.
7

Unload

onUnload() is called on server shutdown or when the plugin is disabled. Use this to close connections and clean up resources.

​
Settings Schema

Plugins declare their settings schema for automatic UI generation. The schema drives both the settings form and validation: 
export interface PluginSettingsSchema {
  credentials: SettingsField[];  // Stored encrypted
  settings: SettingsField[];     // Stored in plaintext
}

export interface SettingsField {
  key: string;
  type: 'text' | 'password' | 'number' | 'boolean' | 'select' | 'url';
  label: string;
  description?: string;
  required?: boolean;
  default?: unknown;
  options?: Array<{ value: string; label: string }>;
}
Fields with type: 'password' are encrypted at rest and never exposed in logs.

​
Plugin Sandbox

By default, plugins from ClawHub run in a Node.js sandbox with restricted access:
  • No direct filesystem access outside the plugin’s data directory
  • Network requests go through the SsrfGuard
  • CPU and memory limits enforced
  • Static code analysis on install
Plugins you install from ClawHub or third parties run code on your machine. Review the source and check the ClawHub trust score before installing plugins from unknown authors.
Trust a plugin to run outside the sandbox (for performance-sensitive use cases): 
profclaw plugins trust @profclaw/plugin-jira-search

​
ClawHub

ClawHub is profClaw’s plugin and skill marketplace. Browse and install from the settings UI at Settings > Plugins > Browse ClawHub, or via CLI: 
# Browse and install
profclaw plugins search jira
profclaw plugins install @profclaw/plugin-jira-search

# Manage installed plugins
profclaw plugins list
profclaw plugins update @profclaw/plugin-jira-search
profclaw plugins disable my-plugin
profclaw plugins remove my-plugin
See Publishing to ClawHub for details on submitting your own plugin.

​
Writing a Plugin

A minimal tool plugin: 
import type { PluginFactory, ToolPlugin } from 'profclaw/sdk';

const factory: PluginFactory<ToolPlugin> = {
  metadata: {
    id: 'my-lookup',
    name: 'My Lookup',
    description: 'Look up data from My API',
    category: 'tool',
    version: '1.0.0',
  },
  settingsSchema: {
    credentials: [
      { key: 'apiKey', type: 'password', label: 'API Key', required: true },
    ],
    settings: [],
  },
  create(config) {
    return {
      tools: [
        {
          name: 'my_lookup',
          description: 'Look up an item by ID',
          schema: z.object({ id: z.string() }),
          securityLevel: 'safe',
          async execute({ id }) {
            const data = await fetchFromApi(config.apiKey, id);
            return { result: data };
          },
        },
      ],
      async healthCheck() {
        return { ok: true };
      },
    };
  },
};

export default factory;
See Plugin SDK Reference for the complete API.

Skills Overview

Add AI behavior with plain Markdown - no code required.

Custom Tools

Add tools directly without packaging a full plugin.

Publishing to ClawHub

Publish your plugin for the community.

Plugin SDK

Full TypeScript SDK reference for plugin development.