# Plugins

> Bundle agents, skills, MCP servers, hooks, and optional capability services into one extension
> that remains inactive until you enable it.

## Manage plugins in the TUI

Type `/extensions/plugins` to open the plugin browser.

1. Press `a`, then enter an HTTPS, SSH, or `file://` Git URL to install a plugin.
2. Select the plugin and inspect every contribution shown in its detail panel.
3. Press `e` to enable it. Clarvis reloads the backend so its contributions are available now; if
   that reload fails, run `/reconnect`.
4. If the plugin contributes hooks, open `/extensions/hooks`, review each exact definition, and
   press `t` for each hook you accept.

Press `u` to update a Git-installed plugin. Press `d` to uninstall a global plugin. Workspace plugins
are part of the repository, so remove them from the repository instead.

::: warning Three separate gates
Installing stores the code. Enabling activates the plugin's contributions. Approving allows one
exact hook definition to run. Completing one step never implies either of the others.
:::

## Create a plugin

A conventional plugin can be as small as this:

```text
quality-kit/
├── plugin.json
├── agents/
│   └── reviewer.md
├── skills/
│   └── quality-check/
│       └── SKILL.md
└── hooks/
    └── hooks.json
```

Put `plugin.json` at the plugin root. The directory name and manifest `name` must match. Names use
lowercase letters, numbers, underscores, and hyphens:

```json
{
  "name": "quality-kit",
  "version": "0.0.1",
  "description": "Review-oriented agents, skills, and checks.",
  "author": {
    "name": "Acme Engineering"
  },
  "mcpServers": {
    "checks": {
      "type": "stdio",
      "command": "quality-kit-mcp",
      "args": ["--stdio"],
      "resources": false
    }
  },
  "hooks": [
    {
      "event": "pre_finalize",
      "command": "bun run lint",
      "timeout_ms": 60000,
      "on_failure": "deny"
    }
  ],
  "bootstrapSkill": "quality-check",
  "capabilityRunPolicies": {
    "plans": {
      "skills": {
        "quality-check": "review"
      }
    }
  }
}
```

The only required manifest field is `name`. If present, `version` must be semantic versioning. You
may declare hooks inline as above; when the manifest declares no hooks, Clarvis also looks for
`hooks/hooks.json`. Relative files and directories named by a manifest must remain inside the plugin.

`bootstrapSkill` names one skill from this plugin whose body should be available before the model
responds. The `review` plan policy asks for planning review on that skill when both the skill and the
selected Plans provider come from this plugin.

## Understand names and overrides

Clarvis qualifies contributions that must be globally unique:

- agents become `<plugin>:<agent>`;
- MCP servers become `<plugin>:<server>`, and their tools become
  `<plugin>:<server>.<tool>`;
- skills keep their skill name and follow normal skill precedence.

For example, the manifest above contributes the MCP namespace `quality-kit:checks`. An agent named
`reviewer.md` is addressed as `quality-kit:reviewer`.

Personal plugins live under `~/.clarvis/plugins/<name>`. A repository may carry a workspace plugin at
`.clarvis/plugins/<name>`; it shadows a personal plugin with the same name. Plugin precedence follows
the order of `enabledPlugins`, with later plugins overriding earlier ones, while your global and
workspace settings always outrank plugin contributions.

## Know what Clarvis accepts

`settings.json` is strict: an unknown top-level setting is an error. `plugin.json` is intentionally
tolerant so a cross-tool plugin is not rejected only because it carries foreign metadata. Clarvis
reports unknown manifest keys but does not act on them. A misspelled key can therefore leave a
contribution inactive even though the plugin loads; review the notes in the plugin browser.

::: warning Enable only code you trust
Plugins may contribute executable MCP servers, agents with their own grants, capability services,
and hooks that run with your privileges. Workspace configuration that enables plugins is withheld
until `/workspace-trust` approval, and every plugin hook still requires its own exact approval.
:::

## See also

- [Marketplaces](/guide/marketplaces)
- [Hooks](/guide/hooks)
- [Skills](/guide/skills)
- [MCP servers](/guide/mcp-servers)
- [Extensions reference](/reference/extensions)

---

[Canonical HTML](https://clarvis.dev/guide/plugins)

[Documentation index](https://clarvis.dev/llms.txt)