plugin.json Manifest Reference

The plugin.json file is the only required file in a plugin. It declares what the plugin provides and how Recursive should load it.

Minimal manifest

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "What this plugin does."
}

Complete schema

Identity

Field	Type	Required	Description
id	string	Yes	Unique plugin identifier. Kebab-case, no spaces. Used in file paths and tool prefixes.
name	string	No	Human-readable display name. Falls back to id if omitted.
version	string	No	Semver version (e.g., "1.2.3"). Used for update checks.
description	string	No	One-line description shown in the plugin list.
author	string | { name: string }	No	Author attribution.
color	string	No	Hex color for the plugin’s icon badge (e.g., "#8b5cf6").
icon	string	No	Icon name from the Recursive icon set.
thumbnail	string	No	Relative path to a thumbnail image for the plugin detail panel.

Capability paths

Each of these fields points to a directory or file that Recursive loads. All paths are relative to the plugin root.

Field	Type	Description
tools	string | string[]	Directory or files containing MCP tool handlers.
routes	string | string[]	Directory or files containing HTTP route handlers.
adapters	string | string[]	Directory or files containing agent adapter implementations.
skills	string | string[]	Directory containing skill subdirectories (each with a SKILL.md).
rules	string | string[]	Directory or files containing agent rule markdown.
workflows	string | string[]	Directory or files containing workflow definitions.
automations	string | string[]	Directory or files containing automation definitions.
hooks	string | string[]	Directory or files containing lifecycle hook handlers.
mcp	string | string[]	External MCP server configuration files.

Tip

When using a string, it can be a directory path (ending in /) or a single file path. When using an array, each entry can be either.

ui — Dashboard extensions

The ui field is an object that declares frontend components and behaviors.

ui.views

Array of view definitions that add new pages to the dashboard.

{
  "ui": {
    "views": [
      {
        "id": "my-view",
        "label": "My View",
        "icon": "layers",
        "route": "my-view",
        "component": "./ui/MyView.svelte",
        "detailPanel": "./ui/MyDetailPanel.svelte"
      }
    ]
  }
}

Field	Type	Description
id	string	Unique view identifier.
label	string	Display name in navigation.
icon	string	Icon name.
route	string	URL route segment (e.g., my-view → /my-view).
component	string	Path to the main Svelte component.
detailPanel	string	Optional path to a detail panel component.

ui.nav

Array of navigation entries added to the sidebar.

{
  "ui": {
    "nav": [
      {
        "route": "my-view",
        "label": "My View",
        "icon": "layers",
        "shortcut": "Mod+5",
        "order": 50,
        "surface": "sidebar.nav.my-view"
      }
    ]
  }
}

ui.commands

Array of command palette entries.

{
  "ui": {
    "commands": [
      {
        "id": "nav-my-view",
        "label": "Go to My View",
        "icon": "layers",
        "section": "Navigation",
        "type": "navigate",
        "route": "my-view",
        "shortcut": "Mod+5",
        "keywords": ["custom", "view"]
      }
    ]
  }
}

ui.panels

Panels added to the workspace detail area (alongside file viewer, preview, etc.).

ui.taskPanels

Panels added to the task detail view.

ui.chatRenderers

Custom renderers for specific tool call results in the chat feed.

{
  "ui": {
    "chatRenderers": [
      {
        "kind": "goal_create",
        "component": "./ui/GoalCreateRenderer.svelte"
      }
    ]
  }
}

ui.entityTypes

Register custom entity types for mention resolution and search.

{
  "ui": {
    "entityTypes": [
      {
        "type": "goal",
        "storeKey": "allGoals",
        "nameKey": "title"
      }
    ]
  }
}

ui.sseEvents

SSE event channels that the plugin’s store should listen to.

ui.store

Path to a TypeScript store module that manages the plugin’s frontend state.

ui.components

Map of named components that other parts of the UI can reference.

settings

Plugin configuration with defaults and a schema for the settings UI.

{
  "settings": {
    "defaults": {
      "api_key": "",
      "enabled_features": ["basic"]
    },
    "schema": [
      {
        "key": "api_key",
        "type": "string",
        "label": "API Key",
        "description": "Your service API key.",
        "section": "Authentication"
      },
      {
        "key": "enabled_features",
        "type": "multi-select",
        "label": "Features",
        "options": ["basic", "advanced", "experimental"],
        "section": "Features"
      }
    ]
  }
}

detect

Auto-detection rules that enable the plugin when a project matches.

{
  "detect": {
    "files": ["package.json", "tsconfig.json"],
    "strategy": "all"
  }
}

Field	Type	Default	Description
files	string[]	—	File patterns to check in the project root.
strategy	"any" | "all"	"any"	Whether any file match suffices or all must be present.

lifecycle

Server-side lifecycle event handlers. Keys are event names, values define the handler.

{
  "lifecycle": {
    "session.complete": {
      "handler": "./hooks/on-session-complete.ts",
      "priority": 10,
      "type": "action"
    }
  }
}

client_lifecycle

Client-side lifecycle event handlers. Same structure as lifecycle but handlers run in the browser.

{
  "client_lifecycle": {
    "session.complete": {
      "handler": "./hooks/client-on-complete.ts",
      "priority": 10
    }
  }
}