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

Recursive installed and running (the server on port 12321)
Node.js 22+ (Recursive requires it)
A text editor

Your first plugin

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
```

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."
}

Add a tool

Create a tools/ directory and add a tool file:

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 };

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/"
}

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.
Test it

Call the tool from any agent session:
```
hello_greet({ name: "Developer" })
```
You should see: Hello, Developer! Welcome to Recursive.

Add a workspace view

A tool is invisible until an agent calls it. The other half of a plugin is UI — your own screen in the Recursive workspace, reachable from the sidebar and the command palette. Let’s add one to the same hello-world plugin.

Write the view component

Create ui/HelloView.svelte. It’s a normal Svelte 5 component — the shell mounts it as a full page:

<script lang="ts">
  let { selectedId = $bindable(null) } = $props();
  let clicks = $state(0);
</script>

<div class="hello-view">
  <header class="content-header">
    <h1>Hello World</h1>
  </header>
  <button onclick={() => clicks++}>Clicked {clicks} times</button>
</div>

Register the view in the manifest

Add a ui block pointing at the component, plus a nav entry so it shows up in the sidebar and a commands entry so ⌘K can jump to it:

{
  "id": "hello-world",
  "name": "Hello World",
  "version": "0.1.0",
  "description": "A minimal plugin that adds a greeting tool and a view.",
  "tools": "./tools/",
  "ui": {
    "views": [
      {
        "id": "hello",
        "label": "Hello",
        "icon": "smile",
        "route": "hello",
        "component": "./ui/HelloView.svelte"
      }
    ],
    "nav": [
      {
        "route": "hello",
        "label": "Hello",
        "icon": "smile",
        "shortcut": "Mod+9",
        "order": 90,
        "surface": "sidebar.nav.hello"
      }
    ],
    "commands": [
      {
        "id": "nav-hello",
        "label": "Go to Hello",
        "icon": "smile",
        "section": "Navigation",
        "type": "navigate",
        "route": "hello",
        "shortcut": "Mod+9",
        "keywords": ["hello", "greeting"]
      }
    ]
  }
}

Reload and open it

Re-enable the plugin (or reload the dashboard). A Hello item appears in the sidebar — click it, or press Mod+9, and your view renders as a full page in the workspace.

That’s the whole loop: a manifest entry, a Svelte component, and your plugin has a home in the workspace. For a real, full-featured reference, open the Xcode plugin at plugins/personal/xcode/ — it ships a view, a detail panel, a workspace panel, a chat renderer, and a live store, all from one ui block. The Custom UI guide walks through each of those surfaces using exactly that plugin.

Plugin locations

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

Location	Path	Use case
Bundled	`plugins/recursive/{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

The typical plugin development workflow:

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

What’s next

Plugin Anatomy — understand the full directory structure and what each capability does
Custom UI — give your plugin views, panels, and command-palette entries in the workspace
Manifest Reference — every field in plugin.json explained
MCP Tools — deep dive into building tools