Plugins

A plugin is a package of agent capabilities. A skill is one set of instructions. A plugin can contain many components together: skills, commands, sub-agent types, MCP servers, hooks, LLM providers and executables. Thus you install a full set of capabilities from one location and turn it on for your agents.

dashsquad plugins use the Claude Code plugin layout. Thus a plugin for Claude Code also works in dashsquad.

Quick startCopy Anchor Link

All these steps occur in Desktop → Settings → Plugins.

The other sections of this page give the details for each step. If you prefer files, you can also put a plugin folder in the plugins folder of the HQ (~/.dash/gateway/plugins/) and edit config.json. Refer to Where plugins live, Configuration → Plugins and the complete example.

Where plugins liveCopy Anchor Link

Installed plugins are in the managed plugins folder of the HQ:

~/.dash/gateway/plugins/
├── config.json          # the state of each plugin (enabled, trusted, source, installed)
└── <plugin-name>/       # one folder for each plugin (its skills, commands and other components)

This is the location for a standalone HQ. For an HQ that Desktop starts, ~/.dash/gateway on this page means ~/.dashsquad/<hq id>. If you run the HQ with --data-dir <path>, the plugins go into <path>/plugins/. Refer to Data folders.

Usually you do not change this folder yourself. The Plugins page in Desktop and the Management API manage it for you. But you can put a plugin into it manually or look at config.json.

Built-in pluginsCopy Anchor Link

dashsquad includes some plugins:

Built-in plugins show the badge Built-in and have no Remove button. To stop a built-in skill plugin, disable it. You cannot disable, untrust or remove the AI providers plugin, because the HQ refuses these changes. Desktop shows no Disable, Revoke trust or Remove button for it. The HQ installs, enables and trusts dash-core-providers again each time it starts.

The Management API refuses an install with the name of a built-in plugin. If you put a plugin with that name into the plugins folder manually, your plugin replaces the built-in plugin. The built-in plugin then shows an error.

Plugin contentsCopy Anchor Link

A plugin is a folder with an optional .claude-plugin/plugin.json manifest and one or more of these components:

The first three components are Markdown. They give only instructions, so they load when the plugin is enabled. The last four components run code or contain credentials. They do nothing until you trust the plugin. Refer to Security model.

The .claude-plugin/plugin.json manifest is optional. It can set name, displayName, description, version, author, homepage, repository, license and keywords. It can also give different paths for skills, commands, agents and providers. If there is no manifest, the name comes from the source or from the folder name. The name must be kebab-case.

Install a pluginCopy Anchor Link

You install a plugin from a source. In Desktop, go to Settings → Plugins, fill in the Install Plugin form and click Install. For scripts, use the Management API: POST /plugins/install.

The installer gets the plugin, scans it and puts it into the managed plugins folder of the HQ at ~/.dash/gateway/plugins/<name>. Then the HQ loads it again. You do not need to restart, but bin/ executables need an HQ restart. Refer to MCP servers, hooks and executables.

The source string has one of three forms:

The installer stops a download after 30 seconds. An archive can have a maximum size of 50 MiB.

Example of an install from git:

POST /plugins/install
{ "source": "git:acme/dash-plugins/research@v1.2.0" }

If the install is successful, the response gives the name, the location on the disk and the source of the plugin. It also gives the version, the description and the result of the scan. The plugin is enabled but not trusted. Its skills and commands work immediately. Its code components wait until you trust the plugin.

To use a different name, give name. If the manifest has a name, the manifest name is used.

Pin a versionCopy Anchor Link

For git sources, add @ref to pin the plugin to a branch, a tag or a commit:

git:acme/dash-plugins/research@main          # a branch (it changes over time)
git:acme/dash-plugins/research@v1.2.0         # a tag
git:acme/dash-plugins/research@9f2c1ab…       # a full commit SHA (recommended)

A full commit SHA is the safest choice, because those bytes cannot change. A branch such as @main always installs the latest version. This is easy, but a later install can bring in different code.

Manage plugins in DesktopCopy Anchor Link

On the Settings → Plugins page in Desktop, you install, examine, enable, trust and remove plugins. You do not have to edit a configuration file. Most changes apply immediately, because the HQ loads the plugins again.

Install Plugin form. The Source field accepts all install sources. Refer to Install a plugin. The Name (optional) field gives a different install name, but a manifest name has priority. Click Install to get, scan and load the plugin. If the scan finds the plugin suspicious, the page shows Warning: scan verdict is "suspicious".

The plugin list. Each installed plugin shows on a card with its name, its version, a status badge and its contributions:

Below the badge, the Contributions: tags show the component types of the plugin. A green tag is active: that component runs. A gray tag with a line through it is not active. For example, a code component of a plugin that is not trusted shows this way until you trust the plugin. An enabled plugin with code components that is not trusted also shows the text Not trusted. Its code components do not run until you trust it.

Controls on each card:

• Enable or Disable: turns the Markdown components (skills, commands and sub-agent types) on or off. Disable also removes the trust of the plugin. If you enable a plugin that has code components, the Trust Plugin dialog opens at once.
• Trust or Revoke Trust: shows only when the plugin is enabled. Trust opens a confirmation (refer to the next section). Revoke Trust stops the code components of the plugin.
• Remove: deletes the plugin folder from your computer, after you confirm in the Remove Plugin? dialog. Built-in plugins do not have this button.

The trust confirmationCopy Anchor Link

When you click Trust, the Trust Plugin dialog opens before code runs. It shows the warning This code will run on your machine. It then lists the code component types that will start when you trust the plugin: bin, hooks, mcp or providers. Click Trust Plugin to confirm, or Cancel to keep the plugin not trusted.

The same dialog opens when you click Enable on a plugin that has code components, because Disable removed the trust. If you click Cancel, the plugin stays enabled but not trusted. Its skills, commands and sub-agent types load. Its code components wait. To trust the plugin later, click Trust on its card.

Security modelCopy Anchor Link

When you install a plugin, you bring the instructions of a different person, and possibly their code, onto your HQ. dashsquad does not trust a new plugin. It uses these protections:

1. Not trusted at install. A new plugin is enabled but not trusted. Its Markdown components (skills, commands and sub-agent types) load. Its code components do nothing: MCP servers, hooks, bin/ executables and provider catalogs wait until you trust the plugin. The install alone cannot run code from the plugin on your HQ.

2. Trust is a separate action. You mark a plugin as trusted after you examine it. An install or the plugin itself cannot do this for you. Trust only plugins whose code you read and that you agree to run in the HQ process. If you disable a plugin, the HQ removes its trust. After you enable the plugin again, you must confirm trust again.

3. A heuristic scan. Before the HQ installs a plugin, it scans these parts:

   • The manifest and the code (bin/, hooks/hooks.json, .mcp.json, providers/), for dangerous patterns. Examples are a download sent into a shell, destructive deletes, prompt injection, secret exfiltration and private keys.
   • The Markdown in skills/, commands/ and agents/, for prompt injection.

   The HQ refuses a plugin that the scan finds dangerous: the install fails, and nothing goes onto the disk. If the scan itself fails, the install also fails. A file that the scan cannot read or parse does not stop the install. Suspicious signals do not stop the install. Examples are environment variable reads, base64 decode operations, or prototype-pollution keys in hooks.json, .mcp.json or provider files. Examine the plugin before you trust it.

4. Path traversal (zip slip) protection. The installer refuses an archive entry whose path goes outside the plugin folder. The path can use ../, an absolute path or a symbolic link. Then the full install fails. A dangerous archive cannot write files outside its own plugin folder. The installer also refuses an archive that contains a hard link, a device file or a FIFO. Then the full install fails with archive member type not allowed.

Provider credentialsCopy Anchor Link

Some plugins contain LLM provider catalogs (providers/*.json) that add AI providers. Examples are a model service in your company, a regional endpoint or a service that is compatible with OpenAI. When you trust a plugin with a catalog, its providers show automatically on the Settings → AI Providers page in Desktop (AI Providers). They show together with the built-in providers: Anthropic, OpenAI, Google, Moonshot (Kimi) and OpenRouter.

You add a key as for a built-in provider. Open AI Providers, select the provider of the plugin and paste your key. Each provider needs its own API key.

More than one key. A provider can have more than one key, for example default and backup, so a second key is ready. The HQ keeps the keys in the same encrypted credential store as the keys of the built-in providers, with these names:

<provider-id>-api-key:<key-name>

For example, a provider with the ID myprov keeps its first key as myprov-api-key:default and a second key as myprov-api-key:backup.

A plugin cannot replace a built-in provider. The built-in IDs are anthropic, openai, google, moonshotai and openrouter. If a plugin uses one of these IDs for a provider, the HQ ignores that provider. This is also true for a trusted plugin.

How to use each componentCopy Anchor Link

When a plugin is loaded (and trusted, if necessary), its components are available in different locations:

SkillsCopy Anchor Link

The skills/<name>/SKILL.md files of a plugin go into the skill index of the agent: the short list of skills in its system prompt. The agent loads the full instructions of a skill with load_skill when it needs them. Refer to Skills for the format.

Commands and sub-agent typesCopy Anchor Link

The commands/<name>.md file of a plugin becomes a command with the name <plugin>:<command>. For example, a plugin with the name research and the file commands/triage.md gives research:triage. The agent can load the command as a skill. In Telegram and WhatsApp, a user can type /research:triage.

The agents/<name>.md file of a plugin (Claude Code sub-agent format) becomes a sub-agent type with the name <plugin>:<agent>. An agent starts it with the agent tool. A sub-agent type is not a command, and the agent cannot load it as a skill.

Commands and sub-agent types are Markdown, so they work when the plugin is enabled. They do not need trust. The plugin name is part of their name, so they cannot have the same name as other components.

MCP servers, hooks and executablesCopy Anchor Link

These are trusted code components. You do not start them with a command. They connect automatically:

• MCP servers (.mcp.json) connect to the HQ. Their tools become part of the tools of the agent. If one server does not start, the HQ writes it to the log and continues without it.
• Hooks (hooks/hooks.json) run automatically at events in a turn. The events are PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, SubagentStart and SubagentStop. Refer to Hooks.
• Executables (bin/) go to the start of the PATH of the HQ. Thus they have priority over the system programs with the same name when a command, a hook or a shell tool runs them.

To stop a PreToolUse or PostToolUse command, select Cancel response in Chat. The command stops, and later hooks for that tool do not start. If you stop a PreToolUse hook, the tool does not run.

LLM providersCopy Anchor Link

The providers/*.json catalogs of a trusted plugin add models. After you trust the plugin and add a key (refer to Provider credentials), the models show in the model list of the agent as <id>/<model-id>. You select them as you select the models of the built-in providers.

Select plugins for each agentCopy Anchor Link

By default, each agent sees all loaded plugins. You can limit an agent to some plugins:

Select AI providers for each agentCopy Anchor Link

The Configuration tab of each agent also has a Providers card. By default it shows All providers (default): the agent can use models from all available AI providers.

Add one or more providers to limit the agent to those providers. The model list of the agent then shows only the models of those providers. If the current model of the agent comes from a provider that you removed, the model stays in the list with the text (not allowed). Select a different model. If an agent tries to use a provider that is not permitted, it gives an error, not a response. To go back to all providers, remove all the chips.

Use this setting when an agent must use only one vendor. For example, you can keep an agent for customers on Anthropic models only, whatever other providers the HQ has.

Config flagsCopy Anchor Link

Each plugin has an entry in ~/.dash/gateway/plugins/config.json with its state. You can see these fields:

An entry can also have a path, to load a plugin from a different folder. Refer to Configuration → Plugins for the full file format.

A complete example pluginCopy Anchor Link

You can copy this small plugin and install it from a local folder. It contains a skill, a command, and an optional LLM provider and hook.

Folder structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── summarize/
│       └── SKILL.md
├── commands/
│   └── triage.md
├── providers/                  (optional — needs trust)
│   └── myprov.json
└── hooks/                      (optional — needs trust)
    └── hooks.json

.claude-plugin/plugin.json: the manifest. The name must be kebab-case. The other fields are metadata.

{
  "name": "my-plugin",
  "displayName": "My Plugin",
  "description": "A summarize skill and a triage command",
  "version": "1.0.0"
}

skills/summarize/SKILL.md: a skill. It is Markdown, so it loads when the plugin is enabled.

---
name: summarize
description: Summarize any text concisely
---
Summarize the provided text in three sentences or fewer.

commands/triage.md: a command with the name my-plugin:triage. The optional frontmatter (name, description) can change the command name and add a description.

---
description: Triage an incoming support ticket
---
Read the ticket below and assign a priority (P1–P4) with a one-line reason.

providers/myprov.json (optional: a credential component, so it works only when the plugin is trusted). The credentialPrefix must be <id>-api-key, and models must contain one or more models.

{
  "id": "myprov",
  "label": "My Provider",
  "credentialPrefix": "myprov-api-key",
  "baseUrl": "https://api.myprov.example/v1",
  "api": "openai-completions",
  "models": [
    { "id": "my-fast", "name": "My Fast", "contextWindow": 128000, "maxTokens": 8192 },
    {
      "id": "my-reasoning",
      "name": "My Reasoning",
      "api": "openai-responses",
      "contextWindow": 128000,
      "maxTokens": 16384,
      "reasoning": true,
      "thinkingLevelMap": { "off": null, "minimal": null, "xhigh": "max" }
    }
  ]
}

Each model can set api to use a different API format from the provider. In this example, my-fast uses Chat Completions and my-reasoning uses Responses. Select the format that your provider supports for that model.

For models that can think before they answer, set reasoning: true and give the limits in thinkingLevelMap:

• reasoning: true tells the HQ that the model can think. It does not make thinking mandatory.
• "off": null makes thinking mandatory. The HQ then selects the lowest available thinking level automatically.
• null removes a level from the supported levels. The example also removes minimal, so its lowest level is low.
• A string connects a dashsquad level to the value of the provider. The example connects xhigh to max.

Use the keys off, minimal, low, medium, high and xhigh. If you do not give a key, the defaults of the provider adapter apply. xhigh is available only if you map it. Refer to the API documentation of the provider for the values that it accepts. Refer to Extended thinking for the default behavior of the HQ.

hooks/hooks.json (optional: it also needs trust). It uses the Claude Code hooks format. Put the events in a top-level hooks object. If there is no hooks object, the HQ finds no hooks. ${CLAUDE_PLUGIN_ROOT} is the folder of the plugin.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/guard.sh" }
        ]
      }
    ]
  }
}

Install it. On the Settings → Plugins page in Desktop, type the folder path in the Source field, for example /Users/you/plugins/my-plugin. Then click Install.

The plugin is enabled but not trusted. The summarize skill and the my-plugin:triage command work immediately. To turn on the provider and the hook, click Trust and confirm. Then add a key for the provider on the Settings → AI Providers page. The myprov/my-fast model is then available for all agents.

What the errors meanCopy Anchor Link

If an install fails, the response code tells you the cause:

If the install is successful but the HQ cannot load the plugins again, the response is 200 with a note and an error.

Not yet supportedCopy Anchor Link

These capabilities are not available:

• Signature checks. The HQ scans each install with heuristics, but it does not do a cryptographic check of a publisher signature.
• npm and registry sources. You can install plugins only from git, URL and local sources. There is no npm: source.
• Marketplaces. You cannot install a plugin by name from a marketplace catalog. Install it from its source.