Skip to main content
Reference

Plugin Reference

Field-level reference for plugin.json fields, directory layout, and Marketplace Schema; see the Plugin page for usage guides.

Plugins are installable extension packages that add commands, agents, skills, hooks, output styles, workflows, and MCP servers to Qoder CLI. This page provides a complete reference for the plugin manifest, directory structure, and marketplace schema. For usage guidelines, see Plugins.

Plugin Manifest (plugin.json)

The manifest file is located at .qoder-plugin/plugin.json and must not be placed in the plugin root directory. This file is optional—if omitted, the CLI loads components from conventional directories and uses the plugin directory name as the plugin name. However, it is recommended to declare it to ensure stable metadata such as name and version.

Required Fields

In plugin.json, only name is required; all other fields are optional.
FieldTypeDescription
namestringThe unique identifier for the plugin (kebab-case, no spaces).

Optional Metadata Fields

FieldTypeDescription
versionstringSemantic version number (e.g., 1.0.0).
displayNamestringHuman-readable name displayed in the UI.
descriptionstringA brief description.
authorobjectAuthor information (name/email/url).
homepagestringURL for documentation or homepage.
repositorystringURL for the source code repository.
licensestringSPDX license identifier (e.g., MIT, Apache-2.0).
keywordsstring[]Tags for search and categorization.
dependenciesarrayOther dependent plugins (marketplace can be specified).

Component Declaration Fields

The following fields are used to override conventional directories or declare components inline (as relative path strings, arrays, or object mappings):
FieldDescription
commandsCommand definitions.
agentsPath to the agent definition file.
skillsPath to the skills directory.
outputStylesOutput style definitions.
workflowsPath / workflowsPathsPaths to workflow files.
hooksHook configuration (relative path to a JSON file or inline configuration).
mcpServersMCP server configuration (relative path to a JSON file or inline configuration).
userConfigDefinitions for user-configurable options.
settingsConfigurations merged when the plugin is enabled. Currently only the agent key is supported; other keys are ignored.

Conventional Directory Structure

If components are not explicitly declared in the manifest, the plugin automatically discovers them in the following conventional directories: 
plugin-name/
├── .qoder-plugin/
│   └── plugin.json      # Recommended: manifest (optional)
├── commands/            # Command definitions (.md)
│   └── subdir/          # Supports nested directories
├── agents/              # Agent definitions (.md)
├── skills/              # Skills directory
│   └── skill-name/
│       └── SKILL.md
├── hooks/
│   └── hooks.json       # Hook configuration
├── output-styles/       # Output style definitions
├── workflows/           # Workflow definitions
├── bin/                 # Executables (added to PATH)
└── .mcp.json            # MCP server configuration
Compatible with mcp.json (without a leading dot) as a fallback for .mcp.json. If both exist, .mcp.json takes precedence, and they are not merged.

Marketplace Manifest (marketplace.json)

A plugin marketplace describes a set of installable plugins via marketplace.json.

Required Fields

FieldTypeDescription
namestringThe name of the marketplace.
ownerobjectMarketplace maintainer information (name/email/url).
pluginsarrayArray of plugin entries.

Optional Fields

FieldTypeDescription
forceRemoveDeletedPluginsbooleanAutomatically uninstall plugins removed from the marketplace.
metadata.pluginRootstringBase path relative to the plugin source.
metadata.versionstringMarketplace version.
metadata.descriptionstringMarketplace description.
allowCrossMarketplaceDependenciesOnstring[]Names of marketplaces allowed for cross-marketplace dependencies.

Plugin Entry Fields

FieldTypeDescription
namestringPlugin name (must match name in plugin.json).
sourcestring/objectPlugin source (relative path, npm, git, github, url, etc.).
categorystringCategory tag.
tagsstring[]Search tags.
strictbooleanWhether a manifest is required in the plugin folder (default true).

Management Commands

In an interactive session, use /plugins (alias /plugin); without a subcommand, it opens the plugin explorer:
SubcommandArgumentsDescription
install (alias i)<plugin>Install a plugin.
uninstall (alias remove/rm)<plugin>Uninstall a plugin.
enable<plugin>Enable a plugin.
disable<plugin>Disable a plugin.
update*<plugin>Update a plugin.
validate<path>Validate a plugin directory or plugin.json.
marketplace (alias market)*—Manage plugin marketplaces, including add <source>, list, remove <name>, and update [name].
reload—Reload all plugins.
From the command line, use qodercli plugins (alias plugin):
SubcommandDescription
listList installed plugins.
install (alias i)Install a plugin from a marketplace or local directory.
uninstall (alias remove/rm)Uninstall a plugin.
enable / disableEnable / disable a plugin.
update*Update a plugin to the latest version from its source marketplace.
validateValidate a plugin in a local directory.
marketplace (alias mp)*Manage plugin marketplaces.
* Commands marked with an asterisk are controlled by the plugin marketplace feature flag and are unavailable when disabled. Startup parameter: --plugin-dir <path> appends additional plugin search directories.

Security

These two settings are placed under the security group in settings.json (a restart is required after modification): 
{
  "security": {
    "blockGitExtensions": true,
    "allowedExtensions": ["^https://github\\.com/my-org/"]
  }
}
  • security.blockGitExtensions: true can block installing/loading plugins from Git.
  • security.allowedExtensions provides a regex allowlist for plugin sources; when non-empty, only matching sources are allowed (overrides blockGitExtensions).

Next Steps

Getting Started
Core Concepts
Using Qoder CLI
Extending Qoder CLI
Remote and Integrations
Configuration and Security
Reference
Troubleshooting