# 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.

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.json`
**Format**: 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](https://microsoft.github.io/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](https://rust-analyzer.github.io/manual.html#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](https://microsoft.github.io/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

1. **Marketplace Installation**:
   - Install marketplace from configured source
   - Read `marketplace.json` to get plugin list

2. **Plugin Installation**:
   - Select appropriate installer (Local/Git) based on `source` configuration
   - Install plugin content to target location

3. **Plugin Activation**:
   - Read the plugin's `plugin.json` manifest
   - Load components based on manifest configuration

4. **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:

1. **Configured Paths**: Paths specified in `plugin.json` or runtime configuration
2. **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

1. **Use Relative Paths**: All file references use relative paths to ensure cross-environment compatibility
2. **Environment Variables**: Use `${CODEBUDDY_PLUGIN_ROOT}` in scripts to reference the plugin directory
3. **Error Handling**: Add appropriate error handling and timeout settings for hook scripts
4. **Complete Documentation**: Provide clear installation and usage instructions in README.md
5. **Semantic Versioning**: Follow semantic versioning conventions to manage plugin versions
6. **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

1. Modify plugin code and resources
2. Update the version field in `plugin.json`
3. Record changes in CHANGELOG.md
4. Commit to version control system
5. 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:

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

### Migration Guide

Migrating from Claude Code to CodeBuddy:

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

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

---

## Related Resources

- **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:

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

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