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