# Manage plugins

Canonical HTML: [Manage plugins](https://getred.dev/docs/plugins). Website source: `b212874eefaf200143affa21c770fbb8855a4f5c`. Documented Red release: v0.9.1. Installer source: `b86a2ca4b92e9547d3b174910c82db8a259f5171`.

Inspect bundled plugins, install external packages, control their lifecycle, and keep native grammar approval explicit.

<a id="inspect-what-red-loaded"></a>

## Inspect what Red loaded

```shell
red --runtime-files
red --self-check
red plugin list
```

`--runtime-files` shows visible plugins and themes with their source. `--self-check` reports the activation status of bundled plugins. `red plugin list` lists installed external packages.

<a id="inspect-plugins-in-the-current-session"></a>

## Inspect plugins in the current session

In Red v0.9.1 and later, run `:plugin-status` or choose **Plugin status** from the command palette. The picker shows configured plugins as active, starting, loads on first use, disabled, or quarantined, and identifies rejected reloads. Problems appear first; the preview includes the full reason and recovery guidance.

Use this view when a plugin command is unavailable or an RPC plugin takes time to initialize. Startup notices explain which command is waiting, and executable failures include the underlying cause. `red plugin list` runs in a separate process and does not report the running editor's session state.

<a id="install-a-package"></a>

## Install a package

```shell
red plugin catalog
red plugin install --catalog go-language
red plugin install owner/repository
red plugin install --path ~/code/my-red-plugin
```

Catalog packages use immutable release archives with recorded checksums. GitHub and local-path sources remain explicitly unreviewed. Installing a package never grants implicit approval to execute a native Tree-sitter grammar.

<a id="run-plugins-written-in-other-languages"></a>

## Run plugins written in other languages

Starting with Red v0.9.0, external plugins can run as JSON-RPC processes over stdio. They can provide commands, panels, pickers, statusline content, and checked document edits. Install and manage these packages with the same `red plugin` commands as Husk packages; install any interpreter or executable required by the package separately.

[Read the JSON-RPC plugin protocol](https://github.com/codersauce/red/blob/v0.9.0/docs/RPC_PLUGIN_PROTOCOL.md)

<a id="try-json-workbench"></a>

## Try JSON Workbench

JSON Workbench is an example JSON-RPC plugin for live jq previews, result exploration, and undoable transformations. It requires Python 3.9 or newer and `jq` on `PATH`. Install it separately from the versioned Red examples:

```shell
git clone --branch v0.9.0 --depth 1 https://github.com/codersauce/red.git red-plugin-examples
red plugin install --path ./red-plugin-examples/examples/rpc-json-workbench
```

Restart Red, open a JSON file, and run `:JsonWorkbench`. Edit the query document, run `:JsonRun`, or enable `:JsonLive` for previews as you edit. Use `:JsonApply` to apply a successful result, `:JsonUndo` to restore the source, and `:JsonCancel` to stop a live or panel preview. Foreground `:JsonRun` and `:JsonQuery` commands finish or reach their query timeout before another command can run in that plugin.

[See JSON Workbench commands and configuration](https://github.com/codersauce/red/blob/v0.9.0/examples/rpc-json-workbench/README.md)

<a id="enable-update-or-remove-a-package"></a>

## Enable, update, or remove a package

```shell
red plugin disable replay
red plugin enable replay
red plugin update replay
red plugin update --all
red plugin remove replay
red plugin remove replay --purge
```

Ordinary removal preserves the plugin's namespaced data for a later reinstall. `--purge` deletes that data as well. Failed updates leave the previous installation active.

<a id="customize-a-bundled-plugin"></a>

## Customize a bundled plugin

```shell
red --eject plugins/fidget.hk
```

The copy in your configuration directory shadows the bundled file. Remove the copy to return to the version shipped with Red.

Husk plugins that spawn processes through the host API need an explicit allowlist:

```toml
[plugin_permissions.project_search]
process = ["rg"]
```

Starting with **v0.9.0**, external packages can also declare a standalone `[rpc]` process in `red-plugin.toml` and talk to Red over newline-delimited JSON-RPC 2.0 in any language. [Write a JSON-RPC plugin in TypeScript or Python](https://getred.dev/docs/plugins/json-rpc.md)