|
|
|
|
@@ -1,30 +1,450 @@
|
|
|
|
|
# Plugins Directory
|
|
|
|
|
|
|
|
|
|
This directory contains plugin references and configurations for Claude Code.
|
|
|
|
|
|
|
|
|
|
## Plugin Categories
|
|
|
|
|
|
|
|
|
|
### Agent Plugins
|
|
|
|
|
- `agent-browse` - Web browsing capabilities for agents
|
|
|
|
|
- `claude-delegator` - Task delegation system
|
|
|
|
|
|
|
|
|
|
### UI/UX Plugins
|
|
|
|
|
- `claude-hud` - Heads-up display for Claude Code
|
|
|
|
|
- `frontend-design` - Frontend design tools
|
|
|
|
|
|
|
|
|
|
### Safety Plugins
|
|
|
|
|
- `claude-code-safety-net` - Safety validation layer
|
|
|
|
|
|
|
|
|
|
### Marketplace
|
|
|
|
|
- `marketplaces` - Plugin marketplace references
|
|
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
Plugins are referenced here and installed via:
|
|
|
|
|
```bash
|
|
|
|
|
npm install <plugin-name>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
Plugin settings go in `~/.claude/settings.json` under `plugins` section.
|
|
|
|
|
# Claude Code Plugin System
|
|
|
|
|
|
|
|
|
|
A Conduit-inspired plugin and hooks system for Claude Code, enabling extensible functionality through GitHub-based plugins, event-driven hooks, and secure sandboxed execution.
|
|
|
|
|
|
|
|
|
|
## Table of Contents
|
|
|
|
|
|
|
|
|
|
- [Features](#features)
|
|
|
|
|
- [Installation](#installation)
|
|
|
|
|
- [Quick Start](#quick-start)
|
|
|
|
|
- [Plugin Development](#plugin-development)
|
|
|
|
|
- [Hooks System](#hooks-system)
|
|
|
|
|
- [CLI Reference](#cli-reference)
|
|
|
|
|
- [Security](#security)
|
|
|
|
|
- [Examples](#examples)
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
|
|
|
|
|
|
### 🎯 Core Capabilities
|
|
|
|
|
|
|
|
|
|
- **GitHub-based Discovery**: Automatically discover plugins from GitHub repositories
|
|
|
|
|
- **Zero-Configuration Install**: One-command installation from any GitHub repo
|
|
|
|
|
- **Event-Driven Hooks**: Hook into any Claude Code event (pre/post execution)
|
|
|
|
|
- **Security Sandboxing**: Isolated execution with permission validation
|
|
|
|
|
- **Command Extensions**: Add custom commands to Claude Code
|
|
|
|
|
- **Tool Extensions**: Extend Claude Code's built-in tools
|
|
|
|
|
- **Version Management**: Track, update, and manage plugin versions
|
|
|
|
|
- **Integrity Checking**: SHA-256 verification for plugin security
|
|
|
|
|
|
|
|
|
|
### 🔐 Security Features
|
|
|
|
|
|
|
|
|
|
- Permission-based access control
|
|
|
|
|
- File system sandboxing
|
|
|
|
|
- Command execution validation
|
|
|
|
|
- Network access control
|
|
|
|
|
- Code injection prevention
|
|
|
|
|
- Binary integrity verification
|
|
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
The plugin system is included with Claude Code. No additional installation required.
|
|
|
|
|
|
|
|
|
|
## Quick Start
|
|
|
|
|
|
|
|
|
|
### Discover Plugins
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# List all available plugins
|
|
|
|
|
claude-plugin discover
|
|
|
|
|
|
|
|
|
|
# Search for specific plugins
|
|
|
|
|
claude-plugin discover git
|
|
|
|
|
claude-plugin discover docker
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Install Plugins
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Install from a marketplace
|
|
|
|
|
claude-plugin install claude-plugins-official hookify
|
|
|
|
|
|
|
|
|
|
# Install directly from GitHub
|
|
|
|
|
claude-plugin install-github username/my-plugin
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Manage Plugins
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# View plugin information
|
|
|
|
|
claude-plugin info hookify
|
|
|
|
|
|
|
|
|
|
# Enable/disable plugins
|
|
|
|
|
claude-plugin enable hookify
|
|
|
|
|
claude-plugin disable hookify
|
|
|
|
|
|
|
|
|
|
# Update plugins
|
|
|
|
|
claude-plugin update hookify
|
|
|
|
|
|
|
|
|
|
# Uninstall plugins
|
|
|
|
|
claude-plugin uninstall hookify
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Plugin Development
|
|
|
|
|
|
|
|
|
|
### Plugin Structure
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
my-plugin/
|
|
|
|
|
├── .claude-plugin/
|
|
|
|
|
│ └── plugin.json # Plugin metadata
|
|
|
|
|
├── commands/ # Command handlers
|
|
|
|
|
│ └── my-command.ts
|
|
|
|
|
├── hooks/ # Hook handlers
|
|
|
|
|
│ └── my-hook.ts
|
|
|
|
|
├── skills/ # Skill definitions
|
|
|
|
|
│ └── my-skill.md
|
|
|
|
|
├── install.sh # Installation script (optional)
|
|
|
|
|
└── uninstall.sh # Uninstallation script (optional)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Plugin Metadata
|
|
|
|
|
|
|
|
|
|
Create a `.claude-plugin/plugin.json` file:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"name": "my-plugin",
|
|
|
|
|
"version": "1.0.0",
|
|
|
|
|
"description": "My awesome plugin for Claude Code",
|
|
|
|
|
"author": "Your Name",
|
|
|
|
|
"license": "MIT",
|
|
|
|
|
"repository": "https://github.com/username/my-plugin",
|
|
|
|
|
"claude": {
|
|
|
|
|
"minVersion": "1.0.0",
|
|
|
|
|
"permissions": [
|
|
|
|
|
"read:files",
|
|
|
|
|
"write:files",
|
|
|
|
|
"execute:commands"
|
|
|
|
|
],
|
|
|
|
|
"commands": [
|
|
|
|
|
{
|
|
|
|
|
"name": "my:command",
|
|
|
|
|
"description": "Does something awesome",
|
|
|
|
|
"handler": "commands/my-command.ts",
|
|
|
|
|
"permissions": ["read:files"]
|
|
|
|
|
}
|
|
|
|
|
],
|
|
|
|
|
"hooks": [
|
|
|
|
|
{
|
|
|
|
|
"event": "PostFileEdit",
|
|
|
|
|
"handler": "hooks/my-hook.ts",
|
|
|
|
|
"priority": 10
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Creating Commands
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
// commands/my-command.ts
|
|
|
|
|
export interface MyCommandOptions {
|
|
|
|
|
input: string
|
|
|
|
|
option?: string
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export async function handle(
|
|
|
|
|
args: MyCommandOptions,
|
|
|
|
|
context: any
|
|
|
|
|
): Promise<string> {
|
|
|
|
|
const { input, option } = args
|
|
|
|
|
|
|
|
|
|
// Your logic here
|
|
|
|
|
return `✓ Command executed with: ${input}`
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export default { handle }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Creating Hooks
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
// hooks/my-hook.ts
|
|
|
|
|
export interface HookContext {
|
|
|
|
|
event: string
|
|
|
|
|
timestamp: string
|
|
|
|
|
data: Record<string, any>
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export async function handle(
|
|
|
|
|
context: HookContext
|
|
|
|
|
): Promise<void> {
|
|
|
|
|
console.log(`Hook triggered: ${context.event}`)
|
|
|
|
|
console.log(`Data:`, context.data)
|
|
|
|
|
|
|
|
|
|
// Your logic here
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export default { handle }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Publishing Your Plugin
|
|
|
|
|
|
|
|
|
|
1. Create a GitHub repository with your plugin
|
|
|
|
|
2. Add the `.claude-plugin/plugin.json` metadata file
|
|
|
|
|
3. Push to GitHub
|
|
|
|
|
4. Users can install with:
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin install-github username/your-plugin
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Hooks System
|
|
|
|
|
|
|
|
|
|
### Available Hook Events
|
|
|
|
|
|
|
|
|
|
| Event | Description | When It Fires |
|
|
|
|
|
|-------|-------------|---------------|
|
|
|
|
|
| `UserPromptSubmit` | User submits a prompt | Before sending to Claude |
|
|
|
|
|
| `PreToolUse` | Before tool execution | Tool about to be used |
|
|
|
|
|
| `PostToolUse` | After tool execution | Tool completed |
|
|
|
|
|
| `PreFileEdit` | Before file edit | File about to be modified |
|
|
|
|
|
| `PostFileEdit` | After file edit | File was modified |
|
|
|
|
|
| `PreCommand` | Before CLI command | Command about to run |
|
|
|
|
|
| `PostCommand` | After CLI command | Command completed |
|
|
|
|
|
| `SessionStart` | Session starts | New session begins |
|
|
|
|
|
| `SessionEnd` | Session ends | Session closing |
|
|
|
|
|
| `PluginLoad` | Plugin loads | Plugin loaded into memory |
|
|
|
|
|
| `PluginUnload` | Plugin unloads | Plugin being unloaded |
|
|
|
|
|
| `Error` | Error occurs | Any error happens |
|
|
|
|
|
|
|
|
|
|
### Hook Priority
|
|
|
|
|
|
|
|
|
|
Hooks execute in priority order (higher = earlier). Default priority is 0.
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"event": "PostFileEdit",
|
|
|
|
|
"handler": "hooks/auto-save.ts",
|
|
|
|
|
"priority": 100
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Registering Hooks via Config
|
|
|
|
|
|
|
|
|
|
You can register hooks in your `.claude/hooks.json`:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"hooks": {
|
|
|
|
|
"PostFileEdit": [
|
|
|
|
|
{
|
|
|
|
|
"hooks": [
|
|
|
|
|
{
|
|
|
|
|
"type": "command",
|
|
|
|
|
"command": "/path/to/hook-script.sh",
|
|
|
|
|
"timeout": 5
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## CLI Reference
|
|
|
|
|
|
|
|
|
|
### `claude-plugin discover [query]`
|
|
|
|
|
List available plugins, optionally filtering by search query.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin discover
|
|
|
|
|
claude-plugin discover git
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin install <marketplace> [plugin-name]`
|
|
|
|
|
Install a plugin from a marketplace.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin install claude-plugins-official hookify
|
|
|
|
|
claude-plugin install claude-plugins-official # List all plugins
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin install-github <repo>`
|
|
|
|
|
Install a plugin directly from GitHub.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin install-github username/my-plugin
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin uninstall <plugin-name> [marketplace]`
|
|
|
|
|
Uninstall a plugin.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin uninstall hookify
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin enable/disable <plugin-name> [marketplace]`
|
|
|
|
|
Enable or disable a plugin without uninstalling.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin enable hookify
|
|
|
|
|
claude-plugin disable hookify
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin update <plugin-name> [marketplace]`
|
|
|
|
|
Update a plugin to the latest version.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin update hookify
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin info <plugin-name>`
|
|
|
|
|
Show detailed information about a plugin.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin info hookify
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin hooks [event]`
|
|
|
|
|
List registered hooks.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin hooks # All hooks
|
|
|
|
|
claude-plugin hooks PostFileEdit # Specific event
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin add-marketplace <name> <github-url>`
|
|
|
|
|
Add a new plugin marketplace.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin add-marketplace my-marketplace https://github.com/user/repo
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `claude-plugin validate <path>`
|
|
|
|
|
Validate a plugin structure and integrity.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin validate /path/to/plugin
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Security
|
|
|
|
|
|
|
|
|
|
### Permissions
|
|
|
|
|
|
|
|
|
|
Plugins request permissions in their `plugin.json`:
|
|
|
|
|
|
|
|
|
|
| Permission | Description |
|
|
|
|
|
|------------|-------------|
|
|
|
|
|
| `read:files` | Read files from the file system |
|
|
|
|
|
| `write:files` | Write files to the file system |
|
|
|
|
|
| `execute:commands` | Execute shell commands |
|
|
|
|
|
| `network:request` | Make network requests |
|
|
|
|
|
| `read:config` | Read Claude Code configuration |
|
|
|
|
|
| `write:config` | Write Claude Code configuration |
|
|
|
|
|
| `hook:events` | Register event hooks |
|
|
|
|
|
| `read:secrets` | Access sensitive data (API keys, etc.) |
|
|
|
|
|
|
|
|
|
|
### Sandboxing
|
|
|
|
|
|
|
|
|
|
Plugins execute in a sandboxed environment with:
|
|
|
|
|
|
|
|
|
|
- **File System**: Access restricted to allowed paths
|
|
|
|
|
- **Commands**: Dangerous patterns blocked (rm -rf /, etc.)
|
|
|
|
|
- **Network**: Domain whitelist/blacklist enforcement
|
|
|
|
|
- **Code**: Injection prevention and sanitization
|
|
|
|
|
|
|
|
|
|
### Integrity Verification
|
|
|
|
|
|
|
|
|
|
All plugins are verified with SHA-256 hashes:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# View plugin integrity
|
|
|
|
|
claude-plugin info my-plugin
|
|
|
|
|
|
|
|
|
|
# Verify manually
|
|
|
|
|
claude-plugin validate /path/to/plugin
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Examples
|
|
|
|
|
|
|
|
|
|
### Example 1: Git Workflow Plugin
|
|
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
- `git:smart-commit` - Auto-stage and commit
|
|
|
|
|
- `git:pr-create` - Create pull requests
|
|
|
|
|
- `git:branch-cleanup` - Clean up merged branches
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin install-github yourusername/git-workflow
|
|
|
|
|
git:smart-commit --type feat --scope api
|
|
|
|
|
git:pr-create --title "Add new feature" --base main
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Example 2: Docker Helper Plugin
|
|
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
- `docker:deploy` - Deploy with zero-downtime
|
|
|
|
|
- `docker:logs` - View and filter logs
|
|
|
|
|
- `docker:cleanup` - Clean up resources
|
|
|
|
|
- `docker:env` - Manage environment variables
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin install-github yourusername/docker-helper
|
|
|
|
|
docker:deploy --env production --no-downtime
|
|
|
|
|
docker:logs --service app --tail 100 --follow
|
|
|
|
|
docker:cleanup --containers --images --volumes
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Example 3: Knowledge Base Plugin
|
|
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
- `knowledge:add` - Add knowledge entries
|
|
|
|
|
- `knowledge:search` - Search knowledge base
|
|
|
|
|
- `knowledge:list` - List all entries
|
|
|
|
|
- `knowledge:export` - Export to JSON/Markdown/CSV
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude-plugin install-github yourusername/knowledge-base
|
|
|
|
|
knowledge:add --content "How to deploy to production" --tags deploy,ops
|
|
|
|
|
knowledge:search --query "deploy" --category ops
|
|
|
|
|
knowledge:export --format markdown
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Architecture
|
|
|
|
|
|
|
|
|
|
### Core Components
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
┌─────────────────────────────────────────────────┐
|
|
|
|
|
│ Claude Code Core │
|
|
|
|
|
└─────────────────────────────────────────────────┘
|
|
|
|
|
│
|
|
|
|
|
┌─────────────┼─────────────┐
|
|
|
|
|
│ │ │
|
|
|
|
|
┌───────▼──────┐ ┌───▼────┐ ┌─────▼─────┐
|
|
|
|
|
│ Plugin │ │ Hook │ │ Security │
|
|
|
|
|
│ Manager │ │ System │ │ Manager │
|
|
|
|
|
└──────────────┘ └────────┘ └───────────┘
|
|
|
|
|
│ │ │
|
|
|
|
|
└─────────────┼─────────────┘
|
|
|
|
|
│
|
|
|
|
|
┌───────▼───────┐
|
|
|
|
|
│ Plugins │
|
|
|
|
|
│ (Sandboxed) │
|
|
|
|
|
└───────────────┘
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Data Flow
|
|
|
|
|
|
|
|
|
|
1. **Installation**: Plugin downloaded from GitHub → Validation → Registration
|
|
|
|
|
2. **Loading**: Plugin metadata read → Security context created → Hooks registered
|
|
|
|
|
3. **Execution**: Command/tool called → Permission check → Sandboxed execution
|
|
|
|
|
4. **Hooks**: Event fires → Hooks executed by priority → Results collected
|
|
|
|
|
|
|
|
|
|
## Contributing
|
|
|
|
|
|
|
|
|
|
We welcome contributions! Please see our contributing guidelines for more information.
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
MIT License - see LICENSE file for details
|
|
|
|
|
|
|
|
|
|
## Support
|
|
|
|
|
|
|
|
|
|
- GitHub Issues: https://github.com/anthropics/claude-code/issues
|
|
|
|
|
- Documentation: https://docs.anthropic.com
|
|
|
|
|
|
|
|
|
|
## Acknowledgments
|
|
|
|
|
|
|
|
|
|
Inspired by [Conduit](https://github.com/conduit-ui/conduit) - the developer liberation platform.
|
|
|
|
|
|