> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enconvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing Plugins

> Install Enconvo, Codex, Claude Code and portable plugins from the store, an archive, GitHub, git, npm, a folder or a plugin marketplace, and keep them up to date.

Most people install plugins from the plugin store on Enconvo's **Plugins** page. Enconvo also installs plugins from other places, including the Codex and Claude Code plugins their developers publish on GitHub and in plugin marketplaces. See [Plugin Formats](/extensions/plugin-formats) for the packages Enconvo reads.

<Warning>
  Only plugins in the Enconvo store are reviewed by Enconvo. A plugin from anywhere else can run programs on your Mac through its MCP servers, so install it only from a source you trust.
</Warning>

## From the Plugins page

Click **Add** on the **Plugins** page:

| Option | What it does |
| - | - |
| **Create plugin** | Starts a chat in which Enconvo's agent builds a plugin with you. |
| **Upload plugin archive…** | Installs a file: an `.enconvo` package, a `.dxt` desktop extension, or a `.zip` of a Claude Code or Codex plugin. |
| **Add from GitHub…** | Installs a plugin, or one from a plugin marketplace, from GitHub, git, npm or a folder (see below). |
| **Add MCP server…** | Opens MCP settings, to connect one server without a plugin around it. |
| **New skill…** | Opens Skills settings, to write a skill of your own. |
| **Developer guide** | Opens [Developing Extensions](/extensions/developing). |

What you've added is under **Installed**, at the top of the **Enconvo** tab: the Connectors you've connected and the plugins you installed or made, by name. Click **Installed** to see all of them. Plugins that come with Enconvo aren't listed there.

### Add from GitHub

Paste where the plugin is and press **Preview**:

* `owner/repo`, or a GitHub link, including one to a folder (`/tree/<branch>/<folder>`)
* `owner/repo/folder` for a plugin inside a repository, with `@branch` or `@tag` to pin a version
* any https git address
* `npm:<package>`, with `@version` to pin one
* an https link to a plugin's `.zip`
* a folder on your Mac

Enconvo shows the plugin before installing anything: its format (Codex, Claude Code, portable, desktop extension or Enconvo), version, developer, skills, MCP servers and hooks, and any ChatGPT apps it includes, which Enconvo doesn't load. For each MCP server it says whether it starts on your Mac or connects over the internet. A plugin's hooks run commands on your Mac, so they stay off unless you check **Allow its hooks to run**. Click **Install**, and Enconvo opens the plugin's page. Its **Source** row says where the plugin came from (for GitHub and git, with the commit) and links to the repository or npm page, and the note at the bottom names the developer the plugin gives: only Enconvo's own plugins and plugins from its store say they're made by Enconvo. Plugins installed this way are listed under **Personal**. Installing again from the same place updates the plugin. If a plugin of the same name is already installed from somewhere else, uninstall it first.

When the address is a plugin marketplace, the dialog lists its plugins with an **Install** button on each. Installing one adds the marketplace, which then shows under **Your marketplaces** the next time you open the dialog.

An Enconvo plugin's source code has to be built before it works, so the dialog gives you the `enconvo plugin install` command to run in Terminal instead.

## From a chat

When you ask Enconvo's agent for something your plugins can't do, it can look for a plugin in the plugin marketplaces on your Mac: the ones you've added in Enconvo, and the ones Codex or Claude Code has that Enconvo doesn't have yet, including the OpenAI Curated marketplace that comes with Codex (see [Marketplaces you added in Codex or Claude Code](#marketplaces-you-added-in-codex-or-claude-code)). It reads the copies of their catalogs already on your Mac and downloads nothing while it looks. It leaves out plugins you've installed, and plugins named like one you've installed from somewhere else.

When it finds one, the agent shows a card in the chat, and nothing installs until you click **Install**:

* From a marketplace you've added in Enconvo, the card says which MCP servers the plugin starts on your Mac or connects to, its skills, and the other plugins it needs.
* From a marketplace only Codex or Claude Code has, the card says that installing adds that marketplace to Enconvo. Enconvo can't read the plugin's contents before then, so the card can't list them.

Either way, the plugin's hooks stay off until you turn them on in **Plugins**. When a plugin can't be installed, for example because a plugin it needs can't be, the agent says so instead of showing the card.

### Plugins from ChatGPT

Plugins in the [ChatGPT plugin directory](https://chatgpt.com/plugins) can't be installed in Enconvo. Most of them are ChatGPT apps, which run only inside ChatGPT, and OpenAI gives the rest of them only to ChatGPT and Codex. If you've signed in to Codex on your Mac, the agent knows the directory from the copy Codex keeps. When you name one of its plugins or paste its chatgpt.com link, the agent tells you why it can't install it and offers something that does the same: a Connector, an MCP server, a skill, or a plugin with the same name in one of your marketplaces. Many of the directory's plugins that come with files also have a plugin of the same name in OpenAI Curated, the marketplace that comes with Codex (OpenAI's public `openai/plugins` repository). The agent offers that plugin, and installing it adds OpenAI Curated to Enconvo. Enconvo doesn't load the ChatGPT apps those plugins include, only their skills and MCP servers.

A chatgpt.com link doesn't work in **Add from GitHub** either; the dialog says the same thing.

## From the command line

`plugin install` takes a plugin from GitHub, git, npm, a zip on the web, a folder or a marketplace. Enconvo 2.5.6 or later has to be running.

```sh theme={null}
npx -p @enconvo/api enconvo plugin install <source>
```

| Source | Example |
| - | - |
| A GitHub repository, optionally a folder in it and a branch, tag or commit | `acme/notes`, `acme/plugins/notes@v1.2.0` |
| A GitHub address | `https://github.com/acme/plugins/tree/main/notes` |
| Any other git repository over https (needs git); an ssh address works only for GitHub | `https://git.example.com/notes.git`, `git@github.com:acme/notes.git` |
| An npm package | `npm:@acme/notes-plugin`, `npm:@acme/notes-plugin@1.2.0` |
| A plugin zip on the web (public https only) | `https://downloads.acme.com/notes-1.2.0.zip` |
| A folder on your Mac | `./notes`, `~/code/notes`, `/Users/ada/notes` |
| A plugin in an added marketplace | `notes@acme-plugins` |

<Note>
  `plugin install` and `plugin marketplace` need an `@enconvo/api` release newer than 0.1.174. Inside a project that depends on `@enconvo/api`, `npx enconvo …` is enough. `marketplace import` also needs Enconvo 2.5.7 or later.
</Note>

Add `--preview` to see what would be installed, and from where, without installing it.

When the source is a plugin marketplace rather than a plugin, `plugin install` lists its plugins. A marketplace with more than 200 lists the first 200 and says how many more there are; `plugin marketplace add` lists them all. Pick one with `--plugin`, which also adds the marketplace:

```sh theme={null}
npx -p @enconvo/api enconvo plugin install acme/plugins --plugin notes
```

### What happens on install

* **Settings**: a plugin with required settings, such as an API key, installs and then asks for them. `plugin install` names them; fill them in on the plugin's page.
* **Enconvo plugins from source**: when a GitHub repository or folder holds an Enconvo plugin that hasn't been built, `plugin install` builds it first. A folder is built in place, after `npm install`.
* **Onboarding**: when a plugin names an onboarding skill, Enconvo offers to run it after the first install.
* **Signing in**: when a plugin's MCP servers need you to sign in, as Notion's or Figma's do, the Plugins page shows **Sign in** as soon as it installs. Enconvo opens the server's sign-in page in your browser and offers the next server once that one connects. `plugin install` names the servers instead. A sign-in you skip waits in **Settings > MCP**.
* **Hooks**: a plugin's [hooks](/extensions/plugin-formats#hooks) install turned off, because they run commands. `--preview` lists them; allow them with the **Allow hooks** switch on the plugin's page. Hooks you allowed stay on through updates that don't change them.
* **Dependencies**: when a Claude Code plugin from a marketplace needs other plugins, Enconvo installs them with it (see [Plugin marketplaces](#plugin-marketplaces)). `--preview` lists them and says which are already installed, which would install, and which can't. A dependency the marketplace entry declares from a marketplace that isn't allowed stops the install; one the plugin's own `plugin.json` declares is left out and the install goes on. Their hooks stay off, and uninstalling the plugin keeps them until you prune them (see [Uninstalling](#uninstalling)).
* **Using it**: as in Codex, type `@` in a chat and pick the plugin, or click one of the prompts under **Try asking** on its page. Either way the chat gets the plugin attached. Every installed plugin is in the `@` menu, including a Codex or Claude Code plugin that names no category.
* **Same name**: installing again from the same source updates the plugin. If a plugin with the same name is already installed from somewhere else, such as the store, Enconvo leaves it alone and asks you to uninstall it first.

When Enconvo isn't running, `plugin install` can still install an Enconvo plugin from GitHub by building it. For anything else, open Enconvo and try again.

### Uninstalling

Uninstall a plugin from its menu or its page on the Plugins page, which asks you to confirm first, or from Terminal:

```bash theme={null}
npx -p @enconvo/api enconvo plugin uninstall notes            # also: remove, rm
npx -p @enconvo/api enconvo plugin uninstall notes --prune    # and the dependencies nothing needs any more
npx -p @enconvo/api enconvo plugin prune --dry-run            # list them without removing anything
npx -p @enconvo/api enconvo plugin prune                      # remove them (also: autoremove)
```

Pruning removes only plugins that were installed because another plugin needed them, once no installed plugin needs them, as `claude plugin prune` does in Claude Code. A plugin you installed yourself is never pruned, and installing a dependency again yourself makes it yours. In Terminal, Enconvo lists what it will remove and asks first; add `-y` to skip the question, which `--prune` needs when it can't ask. The Plugins page's uninstall doesn't prune yet.

## Plugin marketplaces

A marketplace is a catalog of plugins in a repository or folder. Enconvo reads both kinds: Codex's `.agents/plugins/marketplace.json` and Claude Code's `.claude-plugin/marketplace.json`.

```sh theme={null}
npx -p @enconvo/api enconvo plugin marketplace add acme/plugins   # GitHub, a git address or a folder
npx -p @enconvo/api enconvo plugin marketplace add acme/plugins --ref v2   # at a branch, tag or commit
npx -p @enconvo/api enconvo plugin marketplace list               # added marketplaces and their plugins
npx -p @enconvo/api enconvo plugin install notes@acme-plugins     # install one of them
npx -p @enconvo/api enconvo plugin marketplace refresh            # fetch them again for new plugins
npx -p @enconvo/api enconvo plugin marketplace remove acme-plugins
```

`refresh` also answers to `upgrade` (Codex's name) and `update` (Claude Code's), and `--ref v2` is the same as `acme/plugins@v2`.

### Marketplaces you added in Codex or Claude Code

If you've added marketplaces in Codex or Claude Code on this Mac, or Codex has fetched its OpenAI Curated marketplace, `marketplace list` shows the ones Enconvo doesn't have yet, and `import` adds them, so you don't type their addresses again:

```sh theme={null}
npx -p @enconvo/api enconvo plugin marketplace import                            # all of them
npx -p @enconvo/api enconvo plugin marketplace import claude-plugins-official    # only these
```

Enconvo finds them in Codex's `~/.codex/config.toml`, its copy of OpenAI Curated, and its personal `~/.agents/plugins/marketplace.json`, and in Claude Code's list of known marketplaces. It only reads those files and changes nothing in either app. OpenAI Curated is added from `openai/plugins` on GitHub. It leaves out the other marketplaces that come with Codex, which hold plugins for Codex's own tools, and Claude Code marketplaces added from the web address of a `marketplace.json` file, which Enconvo doesn't add. When both apps have a marketplace of the same name, it offers Codex's.

A marketplace's plugins can come from a folder in the marketplace, another GitHub repository, a git address, a folder in a git repository, npm, or a zip on the web (Claude Code's `archive` source). A plugin a Codex marketplace marks `NOT_AVAILABLE` can't be installed.

Codex marketplaces such as OpenAI Curated list only each plugin's name and where it comes from. For a plugin in the marketplace's own folder, Enconvo shows the title, description, category and developer from the plugin's manifest, as Codex does, and the agent finds it by what it does as well as by name. What a marketplace entry says itself comes first.

Some of OpenAI Curated's plugins, such as Gmail, Google Drive, Outlook and Teams, work only when you sign in to Codex with ChatGPT, so Codex doesn't offer them to people who sign in with an API key. Enconvo doesn't sign in to ChatGPT either, so it shows them as needing a ChatGPT sign-in, doesn't install them, and the agent doesn't offer them. For those services, add the provider's own MCP server or a Connector instead.

A folder source written as `./plugins/notes` is read from the top of the marketplace. A bare name such as `notes` is read from the folder `metadata.pluginRoot` names, as in Claude Code, and needs that field.

A download from GitHub, npm or the web can take up to three minutes; if it takes longer, Enconvo stops it and asks you to check your connection.

A zip, whether you paste its link or a marketplace lists it, downloads only from a public https address, through at most five redirects. When the marketplace gives its `sha256`, a download that doesn't match is refused. The plugin can sit at the top of the zip or inside one folder.

Claude Code marketplace entries work with a plugin's own `plugin.json` the way Claude Code reads them:

* An entry can add `commands`, `agents`, `skills`, `outputStyles` and `themes` to the plugin's own, and its `hooks` replace the plugin's hooks for the same events.
* An entry with `"strict": false` that also lists any of these, over a plugin that has a `plugin.json`, is refused as conflicting manifests. Keep them in one place.
* When the plugin has no `plugin.json`, the entry is its manifest.
* The entry's name, description, author and other listing details are shown; the version is the plugin's.
* A marketplace's `renames` are followed. A plugin installed under its old name keeps updating under the new one, and installing by the old name finds it. A name renamed to `null` was removed from the marketplace, and Enconvo says so. If the plugin's own manifest changed its name too, Enconvo asks you to uninstall the old plugin and install the new one, because Enconvo names a plugin after its manifest.
* A plugin's `dependencies`, in its entry or its `plugin.json`, install with it. Each is a name (`"formatter"`), a name and marketplace (`"formatter@acme-tools"`), either followed by a `^` range (`"formatter@acme-tools@^2.1"`), or `{ "name", "marketplace", "version" }` with a semver range. A dependency comes from the plugin's own marketplace unless it names another one, and another marketplace has to be listed in `allowCrossMarketplaceDependenciesOn` by the marketplace you installed from. A dependency with a `version` range installs at the highest release tag (`<plugin>--v<version>`) in that range, and in the ranges other installed plugins put on it, from the plugin's own repository or, for a plugin inside the marketplace, the marketplace's (a marketplace folder counts when it's in a git repository). With no such tag, a plugin inside the marketplace installs as the marketplace has it, and one in its own repository is refused. Ranges no single version satisfies refuse the install, and updates stay inside the ranges. A dependency that's already installed is left as it is, and one outside its `version` range gets a warning.

On the Plugins page, open **Add → Add from GitHub…** and paste the marketplace's address, or pick one you've added under **Your marketplaces**.

Enconvo keeps a copy of a marketplace from GitHub or git, and reads a folder marketplace where it is. Removing a marketplace keeps the plugins you installed from it.

Before you share a marketplace, check it and every plugin in it. The rules are the ones `claude plugin validate` applies, plus Codex's for an `.agents/plugins/marketplace.json`; see [Validation Codes](/extensions/validation-codes#marketplaces). An error means Claude Code can't add the marketplace or install the plugin, even though it may still list it: a field of the wrong type in an entry, `renames` that don't lead to a plugin, `relevance` signals it refuses, or a marketplace name that looks like one of Anthropic's own, such as `claude-plugins-hub`. A warning covers what Claude Code ignores, such as a misspelled field, and names Claude Desktop rejects.

```sh theme={null}
npx -p @enconvo/api enconvo plugin validate path/to/marketplace
```

## Updates

Enconvo's plugin update check also covers plugins installed from GitHub, git, npm, folders and marketplaces, and lists their updates with the store's. It reads a repository's latest commit without downloading it, asks npm for the latest version, notices when an installed folder has changed, and, for a zip a marketplace pins by `sha256`, notices when the pin changes. Updating installs the plugin again from the same source.

To check one plugin, open its page and choose **Check for updates** in the **⋯** menu. When a newer version is there, click **Update** in the message that appears.

Or update one from Terminal, as `claude plugin update` does in Claude Code:

```bash theme={null}
npx -p @enconvo/api enconvo plugin update notes                # from wherever it came from, or the store
npx -p @enconvo/api enconvo plugin update notes@acme-plugins   # only if it came from that marketplace
```

It checks first. When nothing is newer, it says the plugin is already at its latest version and changes nothing; otherwise it updates the plugin the way the Updates list does.

## Publish your own

To list a plugin in the Enconvo store, see [Plugin Store Guidelines](/extensions/publishing-guidelines). To share it without the store, push it to GitHub or a marketplace, and people can install it with **Add from GitHub…** or the commands above.

### Tag a release

`plugin tag` marks the commit you're releasing with a git tag named `<plugin>--v<version>`, as `claude plugin tag` does. Claude Code and Enconvo pick among these tags when another plugin's dependency asks for a version range, and anyone can install that release with Enconvo, for example `acme/plugins/notes@notes--v1.2.0`.

```sh theme={null}
npx -p @enconvo/api enconvo plugin tag plugins/notes --dry-run   # check, and print the git commands
npx -p @enconvo/api enconvo plugin tag plugins/notes --push      # tag HEAD and push the tag to origin
```

The version comes from the plugin's manifest, or from its marketplace entry when the manifest has none, and has to be semver (`1.2.0`). Before tagging, `plugin tag` checks the plugin as `plugin validate` does, and stops when the marketplace entry names a different version, when files in the plugin's folder aren't committed, or when the tag exists. Bump the version for a new release; `--force` moves an existing tag instead. It tags Codex, Claude Code, portable and Enconvo plugins alike, so every manifest the package carries has to name the same version. `-m` sets the tag's message (`%s` is the version), and `--remote` the remote `--push` pushes to. Like `plugin install`, it needs an `@enconvo/api` release newer than 0.1.174.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.