Plugin SDK

A plugin is a folder with a manifest. It can add results to search and actions to command mode. No SDK to install, no runtime to embed.

How loading works

Nex reads each entry in plugin_paths. A path can be a folder of manifests, or a manifest file directly; subfolders are not scanned. Every .json file in those folders is parsed and validated; a file that fails is logged and skipped, which means one bad plugin cannot take the panel down.

The registry is built when Nex starts. Restart after adding or editing a plugin.

Layout

Plugin folder

%APPDATA%\Nex\plugins\
└── workspace.json

Manifest

The top level describes the plugin and holds two lists.

idstringStable identifier for the plugin.

namestringDisplay name. Used as the default subtitle for its actions.

versionstringFree form. Useful while you iterate.

enabledboolSet false to keep a plugin on disk but out of the registry.

provider_itemsarrayStatic entries added to search results.

actionsarrayCommands that appear in command mode.

Provider items

Each item becomes one row in search. They are static: there is no call back into a plugin at query time. A row is searchable but does nothing when selected yet, so pair it with an action that opens the same path.

idstringUnique across the plugin.

kindstringfile or folder. Decides the icon on the row.

titlestringThe result text.

pathstringAbsolute path to open.

Actions

Actions appear in command mode. open_path hands a path to the shell; command starts a process with arguments, and stays blocked while safe mode is on.

idstringUnique across the plugin.

titlestringThe command name in command mode.

subtitlestringSecondary line under the title.

keywordsstring[]Extra terms that should match this action.

typestringopen_path or command. Defaults to open_path.

pathstringUsed by open_path.

commandstringUsed by command. Blocked when safe mode is on.

argsstring[]Arguments passed to the command.

A complete plugin

One provider item and two actions. On Windows paths inside JSON, every backslash is doubled.

workspace.json

{
  "id": "workspace",
  "name": "Workspace",
  "version": "0.1.0",
  "enabled": true,
  "provider_items": [
    {
      "id": "ws-notes",
      "kind": "file",
      "title": "Team notes",
      "path": "C:\\Users\\me\\notes\\team.md"
    }
  ],
  "actions": [
    {
      "id": "open-notes",
      "title": "Open team notes",
      "subtitle": "Workspace",
      "keywords": ["notes", "team"],
      "type": "open_path",
      "path": "C:\\Users\\me\\notes\\team.md"
    },
    {
      "id": "sync",
      "title": "Sync workspace",
      "subtitle": "Workspace",
      "keywords": ["sync", "git"],
      "type": "command",
      "command": "git",
      "args": ["pull"]
    }
  ]
}

Safe mode

plugins_safe_mode is on by default and blocks command actions entirely. Provider items and open_path actions keep working. Turn it off only for plugins you wrote or have read.

config.toml

plugins_enabled = true
plugins_safe_mode = true
plugin_paths = [
  "C:\\Users\\you\\AppData\\Roaming\\Nex\\plugins",
]

What is not here yet

This is a preview surface, and it is honest about it. There is no WASM runtime, no network API, no query-time callback from a plugin, and no extension store. A plugin is data: static results and process launches. Provider rows are not clickable yet, and actions have no icon or confirmation step. If that covers your integration, it works today. If it needs to compute at query time, it does not.

Source

The loader is in apps/core/src/plugin_sdk.rs. Open an issue if a field you need is missing.

Configuration reference What the panel does