CodeBuddy Plugin Reference

Overview

The CodeBuddy plugin system allows you to extend the AI assistant's functionality through a standardized plugin mechanism. Plugins can provide custom commands, agents, skills, hooks, MCP servers, and LSP servers.

I. Plugin Component Reference

Plugins can provide six types of components:

1. Commands

Location: commands/ directory in the plugin root Format: Markdown files with frontmatter

Functionality:

Add custom slash commands
Seamlessly integrate with the CodeBuddy command system

Frontmatter Configuration:

markdown

---
description: Command description
allowed-tools: Read,Write,Bash
argument-hint: Argument hint
model: Model ID or name to use
---

Command prompt content

Command File Organization:

Supports nested subdirectory organization
Subdirectory paths are converted to command names using colon separators
Example: commands/deploy/production.md → command name deploy:production

2. Agents

Location: agents/ directory in the plugin root Format: Markdown files with frontmatter

Frontmatter Configuration:

markdown

---
name: Agent name (optional, defaults to filename)
description: Agent description
model: Model ID or name to use
tools: Read,Write,Bash (comma-separated list of available tools)
color: #FF5733 (agent display color, optional)
---

Agent instruction content

Features:

Agents can be invoked as tools by the main agent
Support custom tool lists
Automatically generate source tags to identify origin

3. Skills

Location: skills/ directory in the plugin root Format: Each skill is a subdirectory containing a SKILL.md file

Directory Structure:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

SKILL.md Frontmatter Configuration:

markdown

---
name: Skill name (optional, defaults to directory name)
description: Skill description
allowed-tools: Read,Write,Bash (list of allowed tools)
---

Skill instruction content

Features:

Skills can include auxiliary files and scripts
The skill's baseDirectory points to the skill directory, allowing access to resource files in the same directory

4. Hooks

Location: hooks/hooks.json in the plugin root, or configured via PluginInfo extension fields in plugin.jsonFormat: JSON configuration containing event matchers and actions

Configuration Example:

json

{
  "PostToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "command",
          "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/format-code.sh",
          "timeout": 30000
        }
      ]
    }
  ]
}

Available Events:

PreToolUse: Triggered before tool use
PostToolUse: Triggered after tool use
UserPromptSubmit: Triggered when user submits a prompt
Notification: Triggered when sending a notification
Stop: Triggered when attempting to stop
SubagentStop: Triggered when sub-agent attempts to stop
SessionStart: Triggered at session start
SessionEnd: Triggered at session end
PreCompact: Triggered before conversation history compression

Hook Types:

command: Execute a shell command or script

Matcher Rules:

Supports regex matching for tool names
Example: "Write|Edit" matches Write or Edit tools

5. MCP Servers

Location:

.mcp.json configuration file in the plugin root
Or configured via PluginInfo extension fields in plugin.json

Configuration Example (.mcp.json):

json

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CODEBUDDY_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CODEBUDDY_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CODEBUDDY_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CODEBUDDY_PLUGIN_ROOT}"
    }
  }
}

Integration Behavior:

MCP servers automatically start when the plugin is enabled
Servers appear as standard MCP tools in the toolkit
Server functionality seamlessly integrates with existing tools

6. LSP Servers

Tip: Need to use an LSP plugin? Install from the official marketplace—search for "lsp" in the /plugin Discover tab. This section describes how to create LSP plugins for languages not covered by the official marketplace.

Plugins can provide Language Server Protocol (LSP) servers to give the AI assistant real-time code intelligence support when working on codebases.

LSP integration provides:

Instant diagnostics: AI assistant sees errors and warnings immediately after each edit
Code navigation: Jump to definition, find references, and hover information
Language awareness: Type information and documentation for code symbols

Location: .lsp.json file in the plugin root, or inline configuration in plugin.json

Format: JSON configuration mapping language server names to their configurations

.lsp.json File Format:

json

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Inline Configuration in plugin.json:

json

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Required Fields:

Field	Description
`command`	The LSP binary to execute (must be in PATH)
`extensionToLanguage`	Maps file extensions to language identifiers

Optional Fields:

Field	Description
`args`	Command-line arguments for the LSP server
`transport`	Communication transport: `stdio` (default) or `socket`
`env`	Environment variables to set when starting the server
`initializationOptions`	Options passed to the server during initialization
`settings`	Settings passed via `workspace/didChangeConfiguration`
`workspaceFolder`	Workspace folder path for the server
`startupTimeout`	Maximum time to wait for server startup (milliseconds)
`shutdownTimeout`	Maximum time to wait for graceful shutdown (milliseconds)
`restartOnCrash`	Whether to automatically restart when the server crashes
`maxRestarts`	Maximum restart attempts before giving up
`loggingConfig`	Debug logging configuration (see below)

Warning: You must install the language server binary separately. LSP plugins configure how CodeBuddy connects to a language server but do not include the server itself. If you see Executable not found in $PATH errors in the /plugin Errors tab, install the required binary for your language.

Available LSP Plugins:

Plugin	Language Server	Installation Command
`pyright-lsp`	Pyright (Python)	`pip install pyright` or `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-lsp`	rust-analyzer	See rust-analyzer installation

Install the language server first, then install the plugin from the marketplace.

II. Plugin Manifest Schema (plugin.json)

Complete Schema Example

json

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "category": "Development Tools",
  "features": ["Feature 1", "Feature 2"],
  "requirements": {
    "node": ">=16.0.0"
  },
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": [
    {
      "name": "custom-server",
      "command": "node",
      "args": ["./servers/custom.js"],
      "env": {
        "SERVER_PORT": "3000"
      }
    }
  ],
  "lspServers": "./.lsp.json"
}

Required Fields

Field	Type	Description	Example
name	string	Unique identifier (kebab-case, no spaces)	"deployment-tools"
description	string	Brief plugin purpose	"Deployment automation tools"

Metadata Fields

Field	Type	Description	Example
version	string	Semantic version	"2.1.0"
author	object	Author information	`{"name": "Dev Team", "email": "[email protected]"}`
homepage	string	Documentation URL	"https://docs.example.com"
repository	string	Source code URL	"https://github.com/user/plugin"
license	string	License identifier	"MIT", "Apache-2.0"
keywords	array	Discovery tags	`["deployment", "ci-cd"]`
category	string	Plugin category	"Development Tools"
features	array	Feature list	`["Auto-deployment", "Log analysis"]`

Component Path Fields (PluginManifest)

Field	Type	Description	Example
commands	string / string[]	Additional command file path array	`["./custom/cmd.md"]`
agents	string / string[]	Additional agent file directory path	"./custom/agents/"
hooks	string / object	Additional hook file or configuration	"./custom/hooks.json"
mcpServers	string / `Record<string,MCPServerConfig>`	MCP server config file path or config object	See MCPServerConfig below
lspServers	string / object	Language Server Protocol configuration for code intelligence (jump to definition, find references, etc.)	`"./.lsp.json"`

MCPServerConfig Structure

typescript

{
  "name": "Server name",
  "command": "Execution command",
  "args": ["Array of command arguments"],
  "env": {
    "ENVIRONMENT_VARIABLE": "value"
  }
}

Runtime Extension Fields (PluginInfo)

Plugins extend the following fields at runtime, supporting more flexible configuration:

Field	Type	Description	Example
agents	string[]	Agent file or directory paths	`["./custom/agents/"]`
commands	string[]	Command file or directory paths	`["./custom/commands/"]`
skills	string[]	Skill file or directory paths	`["./custom/skills/"]`
hooks	`Record<string, any>` \| string	Hook configuration object or file path	"./hooks/custom.json"
mcpServers	`Record<string, McpConfig>` \| string	MCP configuration object or file path	"./mcp-config.json"
lspServers	`Record<string, LspConfig>` \| string	LSP configuration object or file path	"./.lsp.json"

Note:

These extension fields are used in marketplace.json to configure how plugins are loaded
Support for direct configuration objects or file path strings
The loader intelligently merges configured paths with default directory scanning results

Path Behavior Rules

Important: Custom paths are supplementary to default directories, not replacements.

If the commands/ directory exists, it will be loaded along with custom command paths
All paths must be relative to the plugin root and begin with ./
Multiple paths can be specified as arrays for flexibility
Paths can point to individual files or directories

Path Resolution Rules:

File paths: Must end with .md (for commands/agents) or be SKILL.md (for skills)
Directory paths: Recursively scans the directory for all qualifying files

Environment Variables

${CODEBUDDY_PLUGIN_ROOT}: Contains the absolute path to the plugin directory. Use this variable in hooks, MCP servers, and scripts to ensure correct paths regardless of installation location.

Compatibility: Also supports the ${CLAUDE_PLUGIN_ROOT} variable name for compatibility with Claude Code plugins.

json

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

III. Plugin Directory Structure

Standard Plugin Layout

enterprise-plugin/
├── .codebuddy-plugin/       # Metadata directory
│   └── plugin.json          # Required: Plugin manifest
├── commands/                # Default commands location
│   ├── status.md
│   └── logs.md
├── agents/                  # Default agents location
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                  # Agent skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                   # Hook configuration
│   └── hooks.json           # Hook configuration file
├── .mcp.json               # MCP server definitions
├── .lsp.json               # LSP server configuration
├── scripts/                # Hooks and utility scripts
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                 # License file
└── README.md               # Plugin documentation

Important:

The .codebuddy-plugin/ or .claude-plugin/ directory contains the plugin.json file
All other directories (commands/, agents/, skills/, hooks/) must be located in the plugin root
The system prioritizes .codebuddy-plugin/ while also supporting .claude-plugin/ for compatibility

File Location Reference

Component	Default Location	Purpose
Manifest	.codebuddy-plugin/plugin.json	Required metadata file
Commands	commands/	Slash command markdown files
Agents	agents/	Sub-agent markdown files
Skills	skills/	Agent skills with SKILL.md files
Hooks	hooks/hooks.json	Hook configuration
MCP servers	.mcp.json	MCP server definitions
LSP servers	.lsp.json	Language server configuration

IV. Marketplace Manifest Schema (marketplace.json)

Complete Schema Example

json

{
  "name": "Enterprise Plugin Marketplace",
  "description": "Internal enterprise plugin collection",
  "version": "1.0.0",
  "owner": {
    "name": "Enterprise Development Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "deployment-tool",
      "description": "Automated deployment tools",
      "version": "1.0.0",
      "source": "plugins/deployment-tool"
    },
    {
      "name": "code-review-bot",
      "description": "Code review bot",
      "version": "2.1.0",
      "source": {
        "source": "github",
        "repo": "company/code-review-bot"
      }
    },
    {
      "name": "security-scanner",
      "description": "Security scanning tool",
      "version": "1.5.0",
      "source": {
        "source": "url",
        "url": "https://github.com/company/security-scanner.git"
      }
    }
  ]
}

Required Fields

Field	Type	Description	Example
name	string	Marketplace name	"Enterprise Plugin Marketplace"
plugins	array	Plugin list	See below

Metadata Fields

Field	Type	Description	Example
description	string	Marketplace description	"Internal enterprise plugin collection"
version	string	Marketplace version	"1.0.0"
owner	object	Owner information	`{"name": "Team", "email": "..."}`

Plugin Entry (MarketplacePluginEntry)

Each plugin entry contains the following fields:

Field	Type	Required	Description
name	string	✓	Plugin unique identifier
description	string	✓	Plugin description
version	string		Plugin version number
source	string \| PluginSource	✓	Plugin source configuration
strict	boolean		Strict mode (compatible with superpowers-marketplace)

PluginSource Configuration

Plugin sources support three types:

1. Local Relative Path (string)

json

{
  "source": "plugins/my-plugin"
}

2. Local Path (object)

json

{
  "source": {
    "source": "local",
    "path": "plugins/my-plugin"
  }
}

3. GitHub Repository

json

{
  "source": {
    "source": "github",
    "repo": "owner/repo-name"
  }
}

4. Git URL

json

{
  "source": {
    "source": "url",
    "url": "https://github.com/owner/repo.git"
  }
}

Marketplace Types

CodeBuddy supports four marketplace types:

Type	Description	source Field
Directory	Local filesystem directory	path: Absolute local directory path
Github	GitHub repository	repo: owner/repo format
Git	Git repository	url: Git repository URL
URL	HTTP/HTTPS remote	url: URL to marketplace.json

V. Plugin Loading Mechanism

Loading Flow

Marketplace Installation:
- Install marketplace from configured source
- Read marketplace.json to get plugin list
Plugin Installation:
- Select appropriate installer (Local/Git) based on source configuration
- Install plugin content to target location
Plugin Activation:
- Read the plugin's plugin.json manifest
- Load components based on manifest configuration
Component Loading:
- Concurrently load all types of extension components
- Merge configured paths with default directory scanning results
- Cache loaded components for performance

Loader Intelligent Merging

Each extension loader intelligently merges content from two sources:

Configured Paths: Paths specified in plugin.json or runtime configuration
Default Scanning: Files in default directories (e.g., commands/, agents/)

Example:

json

{
  "commands": ["./custom/deploy.md"],
  // Actually loads:
  // - ./custom/deploy.md (configured path)
  // - All .md files in commands/ directory (default scanning)
}

Command Name Generation Rules

Filename: command.md → command name: command
Subdirectory: deploy/prod.md → command name: deploy:prod
Plugin prefix: Automatically adds plugin name as prefix, e.g., plugin-name:command

Agent and Skill Tags

All agents and skills loaded from plugins automatically receive the following tags:

Source tag: (plugin-name@marketplace-name)
Type tag: plugin
Custom tags: custom-agent or custom-command

VI. Debugging and Development Tools

View Plugin Loading Logs

Use the --verbose parameter to view detailed plugin loading information:

bash

codebuddy --verbose

Display Content:

Which plugins are being loaded
Any errors in plugin manifests
Command, agent, and skill registration
MCP server initialization
Hook configuration loading

Common Troubleshooting

Issue	Cause	Solution
Plugin not loaded	Invalid plugin.json	Validate JSON syntax, check required fields
Command not appearing	Incorrect directory structure	Ensure commands/ is in plugin root
Hook not triggering	Script not executable	Run `chmod +x script.sh`
MCP server fails	Missing environment variables	Use `${CODEBUDDY_PLUGIN_ROOT}`
Path errors	Using absolute paths	All paths must be relative and start with `./`
Metadata directory not recognized	Using incorrect directory name	Use `.codebuddy-plugin/` or `.claude-plugin/`
LSP `Executable not found in $PATH`	Language server not installed	Install the binary (e.g., `npm install -g typescript-language-server typescript`)

Plugin Development Best Practices

Use Relative Paths: All file references use relative paths to ensure cross-environment compatibility
Environment Variables: Use ${CODEBUDDY_PLUGIN_ROOT} in scripts to reference the plugin directory
Error Handling: Add appropriate error handling and timeout settings for hook scripts
Complete Documentation: Provide clear installation and usage instructions in README.md
Semantic Versioning: Follow semantic versioning conventions to manage plugin versions
Test Coverage: Test plugin installation and functionality across different environments

VII. Version Management Reference

Semantic Versioning

Follow semantic versioning for plugin releases:

MAJOR version: Incompatible API changes
MINOR version: Backwards-compatible feature additions
PATCH version: Backwards-compatible bug fixes

Example: 1.2.0 → 1.2.1 (fix) → 1.3.0 (new feature) → 2.0.0 (breaking change)

Plugin Update Process

Modify plugin code and resources
Update the version field in plugin.json
Record changes in CHANGELOG.md
Commit to version control system
Users update plugin through marketplace

VIII. CLI Command Reference

Marketplace Management

bash

# Add marketplace
codebuddy plugin marketplace add <source> [--name <name>]

# List marketplaces
codebuddy plugin marketplace list

# Update marketplace
codebuddy plugin marketplace update <name>

# Remove marketplace
codebuddy plugin marketplace remove <name>

Plugin Management

bash

# Install plugin
codebuddy plugin install <plugin-name> <marketplace-name>

# List installed plugins
codebuddy plugin list [--marketplace <name>]

# Enable plugin
codebuddy plugin enable <plugin-name> <marketplace-name>

# Disable plugin
codebuddy plugin disable <plugin-name> <marketplace-name>

# Uninstall plugin
codebuddy plugin uninstall <plugin-name> <marketplace-name>

# Update plugin
codebuddy plugin update <plugin-name> <marketplace-name>

Marketplace Source Formats

Supports the following formats for adding marketplaces:

bash

# Local directory
codebuddy plugin marketplace add /path/to/marketplace

# GitHub shorthand
codebuddy plugin marketplace add owner/repo

# Git URL
codebuddy plugin marketplace add https://github.com/owner/repo.git

# HTTP URL (marketplace.json)
codebuddy plugin marketplace add https://example.com/marketplace.json

IX. Compatibility with Claude Code

The CodeBuddy plugin system is designed to be compatible with the Claude Code plugin specification, with the following differences:

Naming Differences

Concept	Claude Code	CodeBuddy
Metadata Directory	`.claude-plugin/`	`.codebuddy-plugin/` (priority) or `.claude-plugin/` (compatible)
Environment Variable	`${CLAUDE_PLUGIN_ROOT}`	`${CODEBUDDY_PLUGIN_ROOT}` (priority) or `${CLAUDE_PLUGIN_ROOT}` (compatible)

Extended Features

CodeBuddy provides the following extensions over Claude Code:

Runtime Configuration: PluginInfo supports runtime extension field configuration
Multiple Metadata Directories: Supports both .codebuddy-plugin/ and .claude-plugin/
Flexible Configuration: Supports both configuration objects and file path configuration methods

Migration Guide

Migrating from Claude Code to CodeBuddy:

Optionally rename .claude-plugin/ to .codebuddy-plugin/
Optionally replace ${CLAUDE_PLUGIN_ROOT} with ${CODEBUDDY_PLUGIN_ROOT} in scripts
If using the mcpServers field, no changes needed (already uses mcpServers)

Note: Keeping the original naming is fully compatible; CodeBuddy will automatically recognize it.

Plugin Development Tutorial - How to create custom plugins
Marketplace Creation Guide - Creating and managing plugin marketplaces
Hooks Deep Dive - Event handling and automation
MCP Integration Documentation - External tool integration
Settings Configuration - Plugin configuration options

Summary

This document provides the complete technical specification for the CodeBuddy plugin system, covering:

Six plugin component types (Commands, Agents, Skills, Hooks, MCP Servers, LSP Servers)
Complete plugin.json manifest schema and field descriptions
marketplace.json marketplace manifest schema
Standard directory structure and file locations
Plugin loading mechanism and intelligent merging rules
CLI commands and debugging tools
Version management best practices
Compatibility notes with Claude Code

Developers can use this reference document to create fully-featured, well-structured CodeBuddy plugins.

CodeBuddy Plugin Reference ​

Overview ​

I. Plugin Component Reference ​

1. Commands ​

2. Agents ​

3. Skills ​

4. Hooks ​

5. MCP Servers ​

6. LSP Servers ​

II. Plugin Manifest Schema (plugin.json) ​

Complete Schema Example ​

Required Fields ​

Metadata Fields ​

Component Path Fields (PluginManifest) ​

MCPServerConfig Structure ​

Runtime Extension Fields (PluginInfo) ​

Path Behavior Rules ​

Environment Variables ​

III. Plugin Directory Structure ​

Standard Plugin Layout ​

File Location Reference ​

IV. Marketplace Manifest Schema (marketplace.json) ​

Complete Schema Example ​

Required Fields ​

Metadata Fields ​

Plugin Entry (MarketplacePluginEntry) ​

PluginSource Configuration ​

1. Local Relative Path (string) ​

2. Local Path (object) ​

3. GitHub Repository ​

4. Git URL ​

Marketplace Types ​

V. Plugin Loading Mechanism ​

Loading Flow ​

Loader Intelligent Merging ​

Command Name Generation Rules ​

Agent and Skill Tags ​

VI. Debugging and Development Tools ​

View Plugin Loading Logs ​

Common Troubleshooting ​

Plugin Development Best Practices ​

VII. Version Management Reference ​

Semantic Versioning ​

Plugin Update Process ​

VIII. CLI Command Reference ​

Marketplace Management ​

Plugin Management ​

Marketplace Source Formats ​

IX. Compatibility with Claude Code ​

Naming Differences ​

Extended Features ​

Migration Guide ​

Related Resources ​

Summary ​

CodeBuddy Plugin Reference

Overview

I. Plugin Component Reference

1. Commands

2. Agents

3. Skills

4. Hooks

5. MCP Servers

6. LSP Servers

II. Plugin Manifest Schema (plugin.json)

Complete Schema Example

Required Fields

Metadata Fields

Component Path Fields (PluginManifest)

MCPServerConfig Structure

Runtime Extension Fields (PluginInfo)

Path Behavior Rules

Environment Variables

III. Plugin Directory Structure

Standard Plugin Layout

File Location Reference

IV. Marketplace Manifest Schema (marketplace.json)

Complete Schema Example

Required Fields

Metadata Fields

Plugin Entry (MarketplacePluginEntry)

PluginSource Configuration

1. Local Relative Path (string)

2. Local Path (object)

3. GitHub Repository

4. Git URL

Marketplace Types

V. Plugin Loading Mechanism

Loading Flow

Loader Intelligent Merging

Command Name Generation Rules

Agent and Skill Tags

VI. Debugging and Development Tools

View Plugin Loading Logs

Common Troubleshooting

Plugin Development Best Practices

VII. Version Management Reference

Semantic Versioning

Plugin Update Process

VIII. CLI Command Reference

Marketplace Management

Plugin Management

Marketplace Source Formats

IX. Compatibility with Claude Code

Naming Differences

Extended Features

Migration Guide

Related Resources

Summary