Plugin Marketplaces

A plugin marketplace is a plugin directory file used to distribute and manage CodeBuddy extensions. It is a JSON-formatted configuration file that lists available plugins and their source information.

Core Features

Centralized Discovery: Browse plugins from multiple sources in one place
Version Management: Automatically track and update plugin versions
Auto-Update: Support enabling auto-update to periodically sync marketplace content
Team Distribution: Share required plugins within organizations
Flexible Sources: Support for Git repositories, GitHub repositories, local paths, and HTTP URLs

Using Plugin Marketplaces

Prerequisites

CodeBuddy installed and running
Basic understanding of JSON file format
For creating a marketplace: Git repository or local development environment

Adding a Plugin Marketplace

1. Add a GitHub Marketplace

bash

/plugin marketplace add owner/repo

The repository must contain a .codebuddy-plugin/marketplace.json file.

2. Add a Git Repository Marketplace

bash

# HTTPS format
/plugin marketplace add https://gitlab.com/company/plugins.git

# SSH format (git@)
/plugin marketplace add git@gitlab.com:company/plugins.git

# .git suffix format
/plugin marketplace add https://example.com/repo.git

3. Add a Local Marketplace (for development)

bash

# Add a local directory containing .codebuddy-plugin/marketplace.json
/plugin marketplace add ./my-marketplace

# Directly add a marketplace.json file path
/plugin marketplace add ./path/to/marketplace.json

4. Add an HTTP Marketplace

bash

# Add a remote marketplace.json via URL
/plugin marketplace add https://url.of/marketplace.json

Installing Plugins from a Marketplace

bash

# Install from a known marketplace
/plugin install plugin-name@marketplace-name

# Interactively browse available plugins
/plugin

Verifying Marketplace Installation

List Marketplaces: Run /plugin marketplace list to confirm the marketplace was added
Browse Plugins: Use /plugin to view available plugins in the marketplace
Test Installation: Try installing a plugin to verify the marketplace is working properly

Team Configuration

Automatically Install Team Marketplaces

Configure in .codebuddy/settings.json:

json

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/codebuddy-plugins"
      }
    },
    "project-specific": {
      "source": {
        "source": "git",
        "url": "https://git.company.com/project-plugins.git"
      }
    }
  },
  "enabledPlugins": {
    "plugin-a@team-tools": true,
    "plugin-b@team-tools": true
  }
}

When team members start CodeBuddy, the system automatically installs these marketplaces and the plugins specified in the enabledPlugins field.

Automatic Installation Flow

Startup Detection: CodeBuddy automatically detects the configuration file on startup
Marketplace Installation: Automatically installs marketplaces from extraKnownMarketplaces that are not yet installed
Plugin Installation: Automatically installs enabled plugins from enabledPlugins that are not yet installed
Background Execution: The installation process executes asynchronously in the background without blocking the startup flow
Logging: The installation process logs detailed information, viewable with --debug

Creating Your Own Marketplace

Prerequisites for Creation

Git repository (GitHub, GitLab, or other git hosting service)
Understanding of JSON file format
One or more plugins to distribute

Creating the Marketplace File

Create .codebuddy-plugin/marketplace.json in the repository root:

json

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0"
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace Schema

Required Fields

Field	Type	Description
name	string	Marketplace identifier (kebab-case, no spaces)
owner	object	Marketplace maintainer information
plugins	array	List of available plugins

Optional Metadata Fields

Field	Type	Description
description	string	Brief marketplace description
version	string	Marketplace version

Plugin Entry Configuration

Required Fields

Field	Type	Description
name	string	Plugin identifier (kebab-case, no spaces)
source	string/object	Plugin source location
description	string	Brief plugin description

Optional Metadata Fields

Field	Type	Description
version	string	Plugin version
author	object	Plugin author information
homepage	string	Plugin homepage or documentation URL
repository	string	Source code repository URL
license	string	SPDX license identifier (e.g., MIT, Apache-2.0)
keywords	array	Tags for plugin discovery and categorization
category	string	Plugin category
strict	boolean	Require plugin.json in plugin folder (default: true)

Component Configuration Fields

Field	Type	Description
commands	string/array	Custom path to command files or directories
agents	string/array	Custom path to agent files
skills	string/array	Custom path to skill files
hooks	string/object	Custom hooks configuration or hooks file path
mcpServers	string/object	MCP server configuration or MCP config path

About the strict field:

strict: true (default): Plugin must contain a plugin.json manifest file, marketplace fields supplement these values
strict: false: plugin.json is optional. If missing, the marketplace entry serves as the complete plugin manifest

Plugin Source Types

1. Relative Path (Local)

For plugins in the same repository:

json

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "description": "My local plugin"
}

2. GitHub Repository

json

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  },
  "description": "Plugin from GitHub"
}

3. Git URL

json

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  },
  "description": "Plugin from Git URL"
}

Advanced Plugin Entry Example

json

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "homepage": "https://docs.company.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": [
    "./agents/security-reviewer.md",
    "./agents/compliance-checker.md"
  ],
  "skills": [
    "./skills/deployment.md",
    "./skills/monitoring.md"
  ],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/validate.sh"
        }]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CODEBUDDY_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CODEBUDDY_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Note: ${CODEBUDDY_PLUGIN_ROOT} is an environment variable that resolves to the plugin's installation directory.

Hosting and Distributing Marketplaces

1. Hosting on GitHub (Recommended)

Steps:

Create a repository: Set up a new repository for the marketplace
Add the marketplace file: Create .codebuddy-plugin/marketplace.json and define plugins
Share with your team: Team members add it using /plugin marketplace add owner/repo

Advantages: Built-in version control, issue tracking, and team collaboration features

2. Hosting on Other Git Services

Any git hosting service can be used for marketplace distribution. For example, using GitLab:

bash

/plugin marketplace add https://gitlab.com/company/plugins.git

3. Hosting via HTTP URL

You can host the marketplace.json file on any HTTP(S) server:

bash

/plugin marketplace add https://example.com/path/to/marketplace.json

4. Using Local Marketplaces for Development

Test marketplaces locally before distribution:

bash

# Add a local marketplace for testing
/plugin marketplace add ./my-local-marketplace

# Test plugin installation
/plugin install test-plugin@my-local-marketplace

Marketplace Management Operations

List Known Marketplaces

bash

/plugin marketplace list

Displays all configured marketplaces along with their sources and status.

Update Marketplace Metadata

bash

/plugin marketplace update marketplace-name

Refreshes the plugin list and metadata from the marketplace source.

Remove a Marketplace

bash

/plugin marketplace remove marketplace-name

Removes the marketplace from configuration.

⚠️ Warning: Removing a marketplace will uninstall all plugins installed from it.

Managing Auto-Updates

You can enable auto-update functionality for marketplaces, where CodeBuddy automatically checks and updates enabled marketplaces on startup.

How to Enable:

Run the /plugin command to enter plugin management interface
Select "Marketplaces" to view the marketplace list
Select the marketplace you want to configure
Select "Enable auto-update" or "Disable auto-update" to toggle the status

Auto-Update Mechanism:

Executed with a 5-second delay on startup, does not affect main flow
Only updates marketplaces that haven't been updated in over 24 hours
Updates between multiple marketplaces are spaced 2 seconds apart to avoid resource contention
Update failures do not affect other marketplaces, errors are logged

Implementation Details

Marketplace Types

CodeBuddy supports the following marketplace types:

Directory (Local Directory): Load plugins from the local filesystem
GitHub: Clone and update plugins from GitHub repositories
Git: Clone and update plugins from any Git repository
URL (HTTP): Download marketplace.json from HTTP(S) URLs

Marketplace Factory Pattern

The MarketplaceFactory creates different marketplace instances based on configuration:

typescript

// Create the corresponding marketplace instance based on source type
switch (sourceType) {
    case MarketplaceType.Directory:
        marketplace = new DirectoryMarketplace();
        break;
    case MarketplaceType.Github:
    case MarketplaceType.Git:
        marketplace = new GithubMarketplace();
        break;
    case MarketplaceType.URL:
        marketplace = new HttpMarketplace();
        break;
    default:
        marketplace = new BaseMarketplace();
        break;
}

Installation Flow

Parse Source: Determine marketplace type based on input string (local path, GitHub repo, Git URL, HTTP URL)
Download/Clone: Download or clone marketplace content based on marketplace type
Read Manifest: Parse the .codebuddy-plugin/marketplace.json file
Save Configuration: Save marketplace information to local storage
Update Cache: Refresh plugin cache and marketplace list

Plugin Installers

CodeBuddy uses plugin installers (PluginInstaller) to handle different plugin source types:

Local Installer: Handles relative path plugins
Git Installer: Handles GitHub and Git URL plugins

Each installer implements the following methods:

support(source): Determine if this plugin source is supported
isInstalled(plugin, targetDir): Check if the plugin is already installed
install(plugin, targetDir): Install the plugin
update(plugin, installedPath): Update the plugin

Troubleshooting

Common Issues

1. Marketplace Fails to Load

Symptoms: Cannot add marketplace or cannot see its plugins

Solutions:

Verify the marketplace URL is accessible
Check that .codebuddy-plugin/marketplace.json exists at the specified path
Ensure JSON syntax is valid
For private repositories, confirm you have access permissions

2. Plugin Installation Fails

Symptoms: Marketplace displays but plugin installation fails

Solutions:

Verify the plugin source URL is accessible
Check that the plugin directory contains required files
For GitHub sources, ensure the repository is public or you have access
Manually test the plugin source by cloning/downloading

3. Git Operations Fail

Symptoms: Errors when cloning or pulling repositories

Solutions:

Ensure Git is installed and available in the command line
Check network connection and proxy settings
Verify Git credentials are configured correctly
Use the --debug flag to view detailed logs

Debugging Tips

Enable Debug Logging:

bash

codebuddy --debug

Manually Verify Marketplace File:

bash

# Check marketplace.json format
cat .codebuddy-plugin/marketplace.json | jq

Test Git Clone:

bash

# Manually test if Git clone succeeds
git clone https://github.com/owner/repo.git /tmp/test-clone

Next Steps

For Marketplace Users

Discover community marketplaces: Search for CodeBuddy plugin collections on GitHub
Contribute feedback: Report issues and suggest improvements to marketplace maintainers
Share useful marketplaces: Help your team discover valuable plugin collections

For Marketplace Creators

Build plugin collections: Create themed marketplaces around specific use cases
Establish versioning: Implement clear versioning and update strategies
Community engagement: Gather feedback and maintain an active marketplace community
Documentation: Provide clear README files explaining marketplace contents

For Organizations

Private marketplaces: Set up internal marketplaces for proprietary tools
Governance policies: Establish plugin approval and security review guidelines
Training resources: Help teams effectively discover and adopt useful plugins

Plugin System - Plugin system overview
Skills System - Creating and using skills
Slash Commands - Creating custom commands
Hooks - Creating event hooks
Settings - Plugin configuration options

Plugin Marketplaces ​

Core Features ​

Using Plugin Marketplaces ​

Prerequisites ​

Adding a Plugin Marketplace ​

1. Add a GitHub Marketplace ​

2. Add a Git Repository Marketplace ​

3. Add a Local Marketplace (for development) ​

4. Add an HTTP Marketplace ​

Installing Plugins from a Marketplace ​

Verifying Marketplace Installation ​

Team Configuration ​

Automatically Install Team Marketplaces ​

Automatic Installation Flow ​

Creating Your Own Marketplace ​

Prerequisites for Creation ​

Creating the Marketplace File ​

Marketplace Schema ​

Required Fields ​

Optional Metadata Fields ​

Plugin Entry Configuration ​

Required Fields ​

Optional Metadata Fields ​

Component Configuration Fields ​

Plugin Source Types ​

1. Relative Path (Local) ​

2. GitHub Repository ​

3. Git URL ​

Advanced Plugin Entry Example ​

Hosting and Distributing Marketplaces ​

1. Hosting on GitHub (Recommended) ​

2. Hosting on Other Git Services ​

3. Hosting via HTTP URL ​

4. Using Local Marketplaces for Development ​

Marketplace Management Operations ​

List Known Marketplaces ​

Update Marketplace Metadata ​

Remove a Marketplace ​

Managing Auto-Updates ​

Implementation Details ​

Marketplace Types ​

Marketplace Factory Pattern ​

Installation Flow ​

Plugin Installers ​

Troubleshooting ​

Common Issues ​

1. Marketplace Fails to Load ​

2. Plugin Installation Fails ​

3. Git Operations Fail ​

Debugging Tips ​

Next Steps ​

For Marketplace Users ​

For Marketplace Creators ​

For Organizations ​

Related Resources ​

Plugin Marketplaces

Core Features

Using Plugin Marketplaces

Prerequisites

Adding a Plugin Marketplace

1. Add a GitHub Marketplace

2. Add a Git Repository Marketplace

3. Add a Local Marketplace (for development)

4. Add an HTTP Marketplace

Installing Plugins from a Marketplace

Verifying Marketplace Installation

Team Configuration

Automatically Install Team Marketplaces

Automatic Installation Flow

Creating Your Own Marketplace

Prerequisites for Creation

Creating the Marketplace File

Marketplace Schema

Required Fields

Optional Metadata Fields

Plugin Entry Configuration

Required Fields

Optional Metadata Fields

Component Configuration Fields

Plugin Source Types

1. Relative Path (Local)

2. GitHub Repository

3. Git URL

Advanced Plugin Entry Example

Hosting and Distributing Marketplaces

1. Hosting on GitHub (Recommended)

2. Hosting on Other Git Services

3. Hosting via HTTP URL

4. Using Local Marketplaces for Development

Marketplace Management Operations

List Known Marketplaces

Update Marketplace Metadata

Remove a Marketplace

Managing Auto-Updates

Implementation Details

Marketplace Types

Marketplace Factory Pattern

Installation Flow

Plugin Installers

Troubleshooting

Common Issues

1. Marketplace Fails to Load

2. Plugin Installation Fails

3. Git Operations Fail

Debugging Tips

Next Steps

For Marketplace Users

For Marketplace Creators

For Organizations

Related Resources