Skip to content
Recursive Docs

Getting Started

Plugins extend Recursive with new capabilities — tools, workflows, adapters, UI views, rules, and more. This guide walks you through creating a minimal plugin, testing it locally, and understanding the development loop.

Prerequisites

Section titled “Prerequisites”
  • Recursive installed and running (the server on port 12321)
  • Node.js 22+ (Recursive requires it)
  • A text editor

Your first plugin

Section titled “Your first plugin”

  1. Create the plugin directory

    Plugins live in ~/.recursive/plugins/local/ for development. Create a directory with a plugin.json manifest:

    Terminal window
    mkdir -p ~/.recursive/plugins/local/hello-world

  2. Write the manifest

    Create ~/.recursive/plugins/local/hello-world/plugin.json:

    {
      "id": "hello-world",
      "name": "Hello World",
      "version": "0.1.0",
      "description": "A minimal plugin that adds a greeting tool."
    }

  3. Add a tool

    Create a tools/ directory and add a tool file:

    Terminal window
    mkdir -p ~/.recursive/plugins/local/hello-world/tools

    Create tools/greet.ts:

    const schema = {
      name: 'hello_greet',
      description: 'Greet a user by name.',
      inputSchema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: 'Name to greet. Required.' },
        },
        required: ['name'],
        additionalProperties: false,
      },
      audience: 'shared',
    };
    

    async function handler(args, ctx) {
      return {
        message: `Hello, ${args.name}! Welcome to Recursive.`,
        greeted_at: new Date().toISOString(),
      };
    }
    

    export { schema, handler };

  4. Register the tools directory in the manifest

    Update plugin.json to point at the tools:

    {
      "id": "hello-world",
      "name": "Hello World",
      "version": "0.1.0",
      "description": "A minimal plugin that adds a greeting tool.",
      "tools": "./tools/"
    }

  5. Enable the plugin

    Use the MCP tool or the Recursive dashboard:

    plugin_toggle({ id: "hello-world", enabled: true })

    Or open the Plugins view in the dashboard and toggle it on.

  6. Test it

    Call the tool from any agent session:

    hello_greet({ name: "Developer" })

    You should see: Hello, Developer! Welcome to Recursive.

Plugin locations

Section titled “Plugin locations”

Recursive discovers plugins from three locations, checked in this order:

LocationPathUse case
Bundledrecursive-plugins/{id}/Ships with Recursive. Cannot be modified.
Installed~/.recursive/plugins/installed/{id}/Installed from the plugin registry.
Local~/.recursive/plugins/local/{id}/Your own plugins under development.

Local plugins take precedence — if you create a local plugin with the same ID as a bundled one, your version wins. This is useful for developing patches against built-in plugins.

Development loop

Section titled “Development loop”

The typical plugin development workflow:

  1. Edit plugin files (tools, rules, skills, etc.)
  2. Recursive hot-reloads plugin changes automatically on the next tool call
  3. Test via the dashboard chat or an agent session
  4. Iterate until the behavior is correct
  5. Publish to the registry or keep it local

What’s next

Section titled “What’s next”