Using plugins

Plugins add commands, keys, panels, statusline segments, pickers and badges on the map to Graphide, and tools for your coding agents. A plugin is a folder with a plugin.toml and, when it computes anything, a TypeScript script.

Some plugins hold only data: themes, icon sets, a Neovim distribution’s keys, language grammars or snippets. Those run no code at all.

Nothing a plugin adds runs until you approve it, and a plugin can reach only what it asked for and you granted.

The plugins Graphide ships with

Plugin	Adds
files	A file tree panel
worktrees	The repository’s worktrees, with their agents and how far each branch is from its base
problems	Language-server problems, in a bottom panel and the statusline
outline	The open file’s symbols as a tree

They are written against the same public interface as any plugin, and the ones that only read are approved by the release they came with.

Install one

gr plugin search markdown              # find plugins by what they do
gr plugin install store:lunarvim       # from Graphide's plugin store
gr plugin install https://github.com/someone/their-plugin
gr plugin install ./my-plugin          # a folder on this computer

A source can be:

• a name in the store, store:<name>, or store:<name>@<version>; a bare name with no folder of that name falls back to the store;
• a public git repository, or a folder in one, on GitHub, GitLab, Codeberg, Bitbucket, Gitea or Forgejo, or any HTTPS git address. It is pinned to the commit you installed;
• a folder on your computer.

A project can also name the plugins its people should use; see Share a plugin.

Approve it

An installed plugin waits for your approval. Before you approve, read what it asks for:

gr plugin review lunarvim

The review says what the plugin adds, each thing it may do in plain words (such as “reads the files in your workspace” or “sends to and reads from api.github.com”), what those mean together, its files, and its panels drawn as text. It approves nothing.

Then approve it, in the app’s list of what needs you, or on a terminal:

gr plugin approve lunarvim

gr plugin approve prints the review again, asks which of the plugin’s requests to grant, and whether to approve the version shown. What you approve is that exact version: its content’s hash, with the grants you chose. If any file of it changes, it waits for your approval again.

Only a person can approve. Graphide refuses an approval that comes from inside a coding agent, so an agent can install a plugin for you but never switch it on. What a plugin may do lists every request a plugin can make.

Manage your plugins

Command	Does
gr plugin list	Every plugin and its state
gr plugin status [name]	How it runs: its handlers’ times and its last errors
gr plugin config <name> key=value	Change one of its settings. key=null puts the default back
gr plugin secret set <name> <key>	Enter a token it needs, with nothing shown as you type
gr plugin disable <name>	Switch it off; nothing is removed
gr plugin enable <name>	Switch it on again, as it was approved
gr plugin update <name>	Fetch its newest version; changes wait for approval
gr plugin rollback <name>	Go back to the version approved before
gr plugin remove <name>	Remove it. A folder of yours is moved aside, not deleted

A plugin’s settings are kept in your config.toml, under [plugins.<name>.settings]. A secret, such as an API token, is kept in your system keychain, never in that file. The plugin’s script never sees it: it is sent only to the one host the plugin named for it, or handed to the plugin’s own MCP server.

When a plugin misbehaves

Each plugin runs in its own process, so a crash, a slow handler or too much memory stops only that plugin. A plugin that runs past its time limits three times in five minutes, or crashes five times in ten, is switched off for the session. If that happens within an hour of approving a new version, Graphide goes back to the version you approved before it.

gr plugin status <name> says why a plugin stopped, and gr plugin reload <name> gives it another go.

Switch every plugin off

# config.toml
plugins_enabled = false

Or start Graphide with GRAPHIDE_PLUGINS=0 for one run. With plugins off, no plugin starts, and gr plugin says how to turn them on and does nothing else. The daemon notices the change within a couple of seconds.

Known limits

• On macOS, a plugin’s programs (exec) and MCP servers do not run yet: the sandbox there cannot keep your workspace read-only. The rest of a plugin runs.