Plugins

A plugin bundles skills and MCP servers, and sometimes commands, agents, or hooks, so you add a whole capability in one step. Since 0.20.0, Maestrly installs plugins itself and gives their skills and MCP tools to every model, whichever provider runs the conversation. You do not need a separate version of a plugin for each model.

Maestrly reads three plugin formats: Agent Plugins (plugin.json), Codex (.codex-plugin/plugin.json), and Claude Code (.claude-plugin/plugin.json).

Open the plugin center

Open Settings → Maestrly Chat → Plugins. The composer links to it too: Browse plugins sits at the bottom of the + menu and of the skills menu. From a conversation on a remote workspaces host, the link opens that host's plugins.

Plugins belong to a host. Use the Settings of selector to choose This computer or a workspaces environment of a server; each one has its own plugins. The center has two views: Browse and Installed. In Browse, search plugins and filter them by Category and Source.

Sources

A source is a public Git repository that lists plugins, as a Codex or Claude Code marketplace does, or a repository that is a single plugin. Maestrly suggests two sources, openai/plugins and openai/community-plugins. Their plugins are listed once you open the source.

To add a source:

Under Sources, choose Add source.
Enter the Repository as an https:// URL or owner/repo. Optionally enter a branch, tag, or commit, and the folders to download, one per line.
Choose Add source.

Adding a source only lists its plugins. Nothing is installed or run until you install a plugin and approve what it needs. Sources need Git on the host, and only public repositories work; one that asks for a sign-in is refused.

Maestrly does not review plugins from third-party sources. Every source other than the two suggested ones is marked Third party, and so are the details of its plugins. Install only plugins from publishers you trust.

Refresh fetches a source again, and installed plugins with a newer version show Update available. Remove stops listing a source's plugins. If plugins from it are installed, you can uninstall them at the same time, or keep the source.

Compatibility

Maestrly offers only what works the same with every model, so switching models never changes what a plugin does. Each plugin is in one of two states:

State	Meaning
Works with every model	Its skills and MCP servers, and the parts Maestrly adapts, work the same whichever provider runs the conversation.
Not compatible	Nothing in it works the same with every model. It is not offered and cannot be installed.

The list shows only plugins that work with every model. Below it, a counter such as 3 plugins don’t work the same with every model opens the plugins left out, each with its reason. A plugin is not compatible when:

it relies on ChatGPT app connectors and ships no MCP server for the same service, so its skills would expect tools that exist only inside OpenAI products;
it has no skill and no MCP server Maestrly can run;
its manifest is invalid, or its source or marketplace rules it out.

Maestrly adapts what it can. A plugin's commands become skills you start yourself with /<plugin>:<command>, its agents become subagents, and Maestrly runs its hooks itself. Parts that work only inside one product, such as app connectors, language servers, and hooks on events Maestrly does not control, are never enabled for any model. They appear in the plugin's details under Not included, each with its reason; none is dropped silently.

An installed plugin that stops being compatible, for example after its files change, stops applying to every conversation. It stays in Installed with its reason, where you can update or uninstall it.

Install a plugin

Open a plugin to see its components, compatibility, license, declared capabilities, the external endpoints its MCP servers reach, its scripts and executables, its requirements, and the settings it asks for. A plugin is code from its publisher, so check the license and the publisher's terms first.

Choose Install. Before anything is installed, Maestrly asks you to:

approve each MCP server that runs as a local process (stdio);
acknowledge that the plugin ships scripts or executables that agents may run, with your approval, through the shell tool;
approve the plugin's hooks, if it has any. Each hook is listed with its event and command. You can install the plugin without them and switch them on later;
choose where the plugin applies: All conversations, or Selected projects of the host;
fill in the settings the plugin asks for. Secret values are masked, stored encrypted on the host, and never shown again.

If the source changed after you opened the plugin, Maestrly shows the new version for you to review before it installs.

Use a plugin

A plugin's skills are named <plugin>:<skill>. They appear in the composer's skills menu and in Settings → Maestrly Chat → Skills, under the plugin's name. You can switch them on and off, add them to skill groups, and override them in a conversation, like your own skills. They are removed only with the plugin. See Maestro, agents, and skills.

Agents

A plugin's agents become subagents named <plugin>-<agent>. Any model can delegate to them with task or a #<plugin>-<agent> mention, like your own agents. The plugin's details list them.

Tools: the tools an agent names map to Maestrly's. Read, Grep, Glob, LS, Bash, Edit, MultiEdit, Write, WebFetch, and WebSearch keep their meaning, and any mcp__… tool becomes access to the enabled MCP servers. WebSearch works only while web search is on in Settings. Tools with no equivalent every model can use, such as Task or TodoWrite, are left out and listed under Not included. An agent that names no tools gets the read-only set.
Model: an agent's model is ignored. It runs on the conversation's model, unless a rule in Settings → Maestrly Chat → Models & agents → Subagent execution profiles chooses another.
Names: an agent file of the project (.claude/agents, .agents/agents) or of your home folder with the same name wins over the plugin's.

Hooks

A plugin's hooks are commands its publisher wrote to run at set moments of a conversation. Maestrly runs them itself, with Claude Code's input and output format, so they behave the same with every model. These are the events it supports; other events, and hooks that are not commands, are listed under Not included.

Event	When	What the hook can do
`SessionStart`	The first turn of a conversation, the first turn on a host where its hooks had not run yet (a moved conversation, for example), and the first after clearing or compacting it	Add context for the model
`UserPromptSubmit`	Each message you send, before it is stored	Add context, or block the message
`PreToolUse`	Before each tool call	Block the call, or change its input
`PostToolUse`, `PostToolUseFailure`	After a tool call succeeds or fails	Add text the model reads with the result
`Stop`	When the agent ends a turn	Keep the agent going with a reason, at most 8 times in a row

Approval: hooks run only after you approve them, at install or later with the Hooks switch under Installed. An update that changes them asks again.
Where: hooks run only in Agent and Design conversations, on the host that runs the conversation, in its folder. They never run in Ask, Plan, or Maestro conversations.
Permissions: a hook can deny a tool call or block a message, but its allow or ask answer never skips Maestrly's own permission request.
Every model: in a conversation with tool hooks, Codex models use Maestrly's shell, file, and web search tools instead of their own, so every call goes through the hooks. Subagents' tool calls run them too.
Messages: a hook's message, failure, or timeout shows above the composer and is not stored in the conversation. When a hook blocks your message, it comes back to the composer. Messages from a bot, the mobile app, or another conversation's agent go through the same hooks.
Time limit: a hook has 60 seconds unless it sets another timeout, up to 10 minutes. Stop ends it.
ChatGPT companion: it cannot run SessionStart, UserPromptSubmit, or Stop hooks, so it does not start in an Agent conversation with a plugin that has them. Switch that plugin's hooks off, or limit where the plugin applies.

MCP servers

A plugin's MCP servers appear in the + menu and in Settings → Maestrly Chat → Tools, marked From <plugin>. Switch a server off in one conversation from the + menu. Switch it off everywhere, or back on, in Plugins.

A server that uses OAuth shows Needs sign-in. Choose Sign in next to it, in Installed or under Tools, and finish in your browser. The sign-in is kept on the host that runs the server, which renews it as needed. Servers that take a token instead ask for it as a setting.

Several accounts

One OAuth server can have several signed-in accounts, for example a personal and a work e-mail. Choose Add account under the server and pick the other account in your provider's account chooser. Each account is named by its e-mail when the provider shares it, or Account 1, Account 2, and so on; choose Rename to change the name. For each account you can:

choose Change to set where it applies: all conversations, or selected projects;
choose Sign in again when it shows Needs sign-in, for example after its sign-in expired;
choose Remove to sign it out.

When a conversation can use several accounts of a server, the model names the account in each call and asks you when it is not clear which one you mean. You can switch an account off for one conversation in the + menu. With a single account, nothing changes.

Own OAuth client

Some servers, such as Google's, do not register apps automatically. Signing in to one shows a form for Your own OAuth client: create a client with the server's provider, of the desktop or native-app type, with a loopback redirect, and enter its Client ID and, if it has one, its Client secret. The secret is kept encrypted on the host that runs the server and is never shown again. Own OAuth client under the server lets you change or remove the client.

With Google:

In Google Cloud Console, open APIs & Services → Credentials → Create OAuth client ID and choose Desktop app.
Enable the service's API in the same project, for example the Gmail MCP API.
On the OAuth consent screen, add your accounts as test users. While the app is in Testing mode, Google ends each sign-in after 7 days, so you sign in again weekly.

Manage installed plugins

Installed lists the host's plugins. For each plugin you can:

switch it on or off, and switch each of its MCP servers and its hooks on or off. Switching hooks on shows them for your approval;
choose Change to set where it applies;
choose Update when its source has a newer version. If the new version changes what runs, such as a new local server, new scripts, or changed hooks, Maestrly asks for your approval again;
choose Edit settings;
choose Uninstall. Its skills and MCP tools leave every conversation, and its saved settings are deleted. Select Also delete the plugin's data to remove the files its servers keep.

A plugin marked Needs settings or Server needs approval is missing a required setting or the approval of a local server. Its MCP servers that need them stay off until you provide them; its skills keep working.

Remote workspaces and bot environments

Remote workspaces

With a workspaces environment selected in Settings of, the plugin center manages that environment's plugins. They are downloaded and run on the server, in that environment, and its conversations use them. Selected projects lists the environment's workspaces. Nothing is copied between this computer and the server, or between environments.

When a conversation moves to another computer or environment, it uses the plugins installed there. What you switched off for it, such as a plugin's server or an account, stays off where the same plugin is installed. Sign-ins are the destination's own.

Bot environments

Open the environment's settings (Environment settings, the gear in the environment view) and choose Plugins. The plugin center works the same way, with these differences:

The environment downloads, checks, and runs its plugins itself, and they serve all of its conversations.
Bring from this computer installs one of this computer's plugins in the environment. The environment downloads it from the same source at the same commit, checks it against the approvals you gave on this computer, and stores the settings you entered here, encrypted. Plugin files are never copied from this computer. If the environment cannot match your approval, install the plugin from the environment's sources and review it there.
Sign in for a server of the environment opens the consent page in this computer's browser. The environment keeps the sign-in, and its accounts serve all of its conversations.
The plugins' skills appear in the environment's Skills settings under each plugin's name.

Update the bot server and the environment first. Until then, the tab asks you to update one or the other. See Bots and the bot server.

Security

A plugin is code from its publisher. Maestrly shows its license, endpoints, local commands, and scripts before you install it, but it does not review plugins from third-party sources.
A skill is instructions, so a malicious one can steer the agent. Its actions still go through Maestrly's permission requests, which do not ask in Full access mode.
Each local MCP server needs your approval of its exact launch command, and so do the scripts and the hooks. An update that changes what runs asks again.
Hooks run commands on the host, with your permissions, without asking each time. They can stop an action, but they cannot approve one for you.
Values you enter for a plugin are stored encrypted on the host and never shown again. Without secure storage on the host, they are refused.
Plugins are downloaded only from public HTTPS Git repositories. Symbolic links and submodules are not installed.
A plugin's local servers run on the host that installed it: this computer, a remote workspaces host, or a bot environment.

For the full details, read the technical guide.

Next: Projects and Git.