@bettercallclaude/sdk

SDK for creating Better Call Claude plugins.

Installation

npm install @bettercallclaude/sdk

Usage

Creating a Hook Plugin

import { BaseHookPlugin, type HookInput, type HookOutput, type PluginManifest } from '@bettercallclaude/sdk'

const manifest: PluginManifest = {
  name: '@myorg/my-plugin',
  version: '1.0.0',
  displayName: 'My Plugin',
  description: 'My awesome plugin',
  capabilities: ['hooks'],
  types: {
    hooks: [
      {
        name: 'pre-tool-use',
        entry: 'dist/hooks/pre-tool-use.js',
      },
    ],
  },
}

export class MyHookPlugin extends BaseHookPlugin {
  constructor() {
    super(manifest)
  }

  async executePreToolUse(input: HookInput): Promise<HookOutput> {
    // Transform input before sending to Claude
    return {
      toolName: input.toolName,
      parameters: input.parameters,
      metadata: {
        pluginId: this.id,
      },
    }
  }

  async executePostToolUse(input: HookInput): Promise<HookOutput> {
    // Transform output after receiving from Claude
    return input
  }
}

Creating a Command Plugin

import { BaseCommandPlugin, type Command, type PluginManifest } from '@bettercallclaude/sdk'

export class MyCommandPlugin extends BaseCommandPlugin {
  constructor() {
    super(manifest)
  }

  getCommands(): Command[] {
    return [
      {
        name: 'hello',
        description: 'Say hello',
        action: async (args, options) => {
          console.log('Hello from my plugin!')
        },
      },
    ]
  }
}

Creating a Pattern Plugin

import { BasePatternPlugin, type Pattern, type PluginManifest } from '@bettercallclaude/sdk'

export class MyPatternPlugin extends BasePatternPlugin {
  constructor() {
    super(manifest)
  }

  getPatterns(): Pattern[] {
    return [
      {
        id: 'my-pattern',
        name: 'My Pattern',
        category: 'custom',
        regex: '\\b[A-Z]{3}-\\d{4}\\b',
        examples: ['ABC-1234'],
      },
    ]
  }
}

Validating Plugin Manifest

import { validatePluginManifest, ValidationError } from '@bettercallclaude/sdk'

try {
  const manifest = validatePluginManifest(yamlData)
  console.log('Manifest is valid!')
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation errors:')
    error.errors.forEach((err) => {
      console.error(`  ${err.path}: ${err.message}`)
    })
  }
}

Plugin Manifest Structure

Every plugin must have a plugin.yaml file:

name: "@myorg/my-plugin"
version: "1.0.0"
displayName: "My Plugin"
description: "My awesome plugin"

capabilities: [hooks, commands, patterns]

types:
  hooks:
    - name: "pre-tool-use"
      entry: "dist/hooks/pre-tool-use.js"
      priority: 100

  commands:
    - name: "hello"
      entry: "dist/commands/hello.js"

  patterns:
    - path: "patterns/custom.yaml"
      category: "custom"

compatibility:
  claudeCode: ">=1.0.0"
  node: ">=18.0.0"

License

MIT