claude-binary-plugin

claude-binary-plugin

Build Claude Code plugins that compile to single-file Bun executables. Define hooks and commands with a declarative pipeline system, Zod-validated inputs/outputs, and built-in OpenTelemetry observability.

Features

• Declarative hook pipelines with full type inference for all 10 Claude Code hook types
• Single-file Bun executables with cross-platform distribution via proxy scripts
• Zod-validated environment options, typed tool inputs, and branded identifiers
• Built-in init scaffolding to go from zero to working plugin in under a minute
• Fluent testing API with shell mocking, temp projects, and full state simulation

Installation

bun add claude-binary-plugin

Requires Bun >= 1.3.9 and Zod >= 4.3.5 as a peer dependency.

Quick Start

Scaffold a new plugin project:

bunx claude-binary-plugin init my-plugin

Or define a plugin manually:

// plugin.config.ts
import { ClaudeBinaryPlugin } from "claude-binary-plugin";
import { z } from "zod";

const plugin = ClaudeBinaryPlugin.create({
  prefix: "MY_PLUGIN",
  options: z.object({
    TIMEOUT_MS: z.coerce.number().default(30000),
  }),
  hooks: {
    PreToolUse: [{
      name: "security",
      tools: ["Bash"],
      pipeline: "./hooks/security.hook.ts",
    }],
  },
});

export default plugin;

Build the plugin:

bunx claude-binary-plugin build

Documentation

Comprehensive documentation is available in the docs directory:

• Getting Started -- zero to working plugin
• Plugin Configuration -- ClaudeBinaryPlugin.create() deep dive
• Hooks -- all 10 hook types with examples
• Commands -- CLI tools compiled into your plugin
• CLI Reference -- build and init command options

License

MIT