SuperCharged-Claude-Code-Upgrade/plugins

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
• Installation
• Quick Start
• Plugin Development
• Hooks System
• CLI Reference
• Security
• 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

# List all available plugins
claude-plugin discover

# Search for specific plugins
claude-plugin discover git
claude-plugin discover docker

Install Plugins

# Install from a marketplace
claude-plugin install claude-plugins-official hookify

# Install directly from GitHub
claude-plugin install-github username/my-plugin

Manage Plugins

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

{
  "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

// 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

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

   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.

{
  "event": "PostFileEdit",
  "handler": "hooks/auto-save.ts",
  "priority": 100
}

Registering Hooks via Config

You can register hooks in your .claude/hooks.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.

claude-plugin discover
claude-plugin discover git

claude-plugin install <marketplace> [plugin-name]

Install a plugin from a marketplace.

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.

claude-plugin install-github username/my-plugin

claude-plugin uninstall <plugin-name> [marketplace]

Uninstall a plugin.

claude-plugin uninstall hookify

claude-plugin enable/disable <plugin-name> [marketplace]

Enable or disable a plugin without uninstalling.

claude-plugin enable hookify
claude-plugin disable hookify

claude-plugin update <plugin-name> [marketplace]

Update a plugin to the latest version.

claude-plugin update hookify

claude-plugin info <plugin-name>

Show detailed information about a plugin.

claude-plugin info hookify

claude-plugin hooks [event]

List registered hooks.

claude-plugin hooks              # All hooks
claude-plugin hooks PostFileEdit  # Specific event

claude-plugin add-marketplace <name> <github-url>

Add a new plugin marketplace.

claude-plugin add-marketplace my-marketplace https://github.com/user/repo

claude-plugin validate <path>

Validate a plugin structure and integrity.

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:

# 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

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

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

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 - the developer liberation platform.