---
title: "Plugins"
---

# Plugins

Install, manage and write CLI plugins that bundle slash commands, sub-agent profiles, skills, hooks and MCP servers into one unit.

A plugin bundles slash commands, sub-agent profiles, skills, hooks and MCP servers into one installable unit, so a team can share a complete workflow with a single command.

## Use plugins

```bash
neuralinverse plugin install ./tools/ni-release           # a local folder (copied)
neuralinverse plugin install https://github.com/acme/ni-k8s.git#v1.2.0
neuralinverse plugin install npm:@acme/ni-plugin-security
neuralinverse plugin list
neuralinverse plugin info ni-k8s                          # what it contributes, including hooks and MCP servers
neuralinverse plugin disable ni-k8s --project             # off for this repository only
neuralinverse plugin enable ni-k8s
neuralinverse plugin update                               # re-install all from their sources
neuralinverse plugin uninstall ni-k8s
```

Plugins install to `~/.neuralinverse/plugins/`. A plugin is active when it is installed and enabled, unless a project's settings turn it off with `"plugins": { "<name>": false }`. In a session, `/plugins` lists active plugins and load problems, and `/reload-plugins` re-reads them without restarting: commands, agents, skills and hooks are replaced and MCP servers reconnect.

Contributions are namespaced by plugin name:

| Contribution | Appears as |
|---|---|
| Command | `/<plugin>:<command>` |
| Agent profile | `<plugin>:<agent>` |
| Skill | `<plugin>:<skill>` |
| MCP server | `<plugin>-<server>` |

Plugin hooks run alongside your own.

Plugins run with your permissions. Install only plugins you trust, and review their hooks and MCP servers with `plugin info <name>` first. Organisation governance and your permission rules still decide every tool call a plugin's command or agent leads to.

## Write a plugin

```text
ni-release/
├── ni-plugin.json
├── commands/notes.md          → /ni-release:notes
├── agents/changelog-writer.md → delegate agent "ni-release:changelog-writer"
├── skills/semver/SKILL.md     → skill "ni-release:semver"
└── scripts/check-tag.sh
```

`ni-plugin.json`:

```json
{
  "name": "ni-release",
  "version": "1.0.0",
  "description": "Release notes, changelog and tagging helpers",
  "author": "Acme Platform Team",
  "license": "MIT",
  "engines": { "neuralinverse": ">=0.1.0" },
  "hooks": {
    "tool.before": [{ "matcher": "run_shell", "command": "\"${NI_PLUGIN_DIR}/scripts/check-tag.sh\"" }]
  },
  "mcpServers": {
    "changelog": { "type": "stdio", "command": "node", "args": ["${NI_PLUGIN_DIR}/server/index.js"] }
  }
}
```

| Field | Rule |
|---|---|
| `name` | kebab-case |
| `version` | semver |
| `engines.neuralinverse` | A semver range the CLI version must satisfy |
| `hooks` | Same format as the [hooks](https://neuralinverse.com/docs/cli/hooks/) setting |
| `mcpServers` | Same format as the [MCP servers](https://neuralinverse.com/docs/cli/mcp/) setting |

- `commands/`, `agents/` and `skills/` use the same formats as project files; see [Instructions, commands and skills](https://neuralinverse.com/docs/cli/extending/).
- `${NI_PLUGIN_DIR}` expands to the installed plugin folder in hook commands and MCP server definitions, and `NI_PLUGIN_DIR` is set in their environment. Quote it: paths may contain spaces.
- Check a plugin before publishing with `neuralinverse plugin validate <dir>`.

Plugins installed from npm are unpacked without running install scripts and without installing dependencies. Ship a self-contained plugin and bundle any JavaScript it needs.