Plugins

Extend Brainstorm with custom tools, hooks, and skills using the Plugin SDK.

Plugins

Brainstorm's plugin system lets you extend the assistant with custom tools, lifecycle hooks, and skills. The @brainstorm/plugin-sdk package provides the typed interfaces and utilities for building plugins.

Plugin Structure

A Brainstorm plugin is an npm package that exports a plugin manifest:

``typescript


import { definePlugin } from '@brainstorm/plugin-sdk';
export default definePlugin({
  name: 'my-plugin',
  version: '1.0.0',
  description: 'Adds custom functionality to Brainstorm',
  tools: [/* custom tools */],
  hooks: [/* lifecycle hooks */],
  skills: [/* skill definitions */],
});


Custom Tools
Define tools with typed input schemas and execution handlers:

`typescript


import { defineTool } from '@brainstorm/plugin-sdk';
import { z } from 'zod';
const myTool = defineTool({
  name: 'deploy_preview',
  description: 'Deploy a preview environment for the current branch',
  permission: 'write',
  inputSchema: z.object({
    branch: z.string().describe('Git branch to deploy'),
    environment: z.enum(['staging', 'preview']).default('preview'),
  }),
  async execute({ input, context }) {
    // Tool implementation

return { url: https://preview-${input.branch}.example.com };


  },
});


Custom tools appear alongside built-in tools in the TUI and are subject to the same permission system.
Lifecycle Hooks
Hooks let you run code at specific points in the Brainstorm lifecycle:
| Hook | Trigger |
|------|---------|

| SessionStart | When a new chat session begins |

| PreToolUse | Before any tool is executed |

| PostToolUse | After a tool completes |

| PreModelCall | Before sending a request to a model |

| PostModelCall | After receiving a model response |

| SessionEnd | When the session is closed |

`typescript


import { defineHook } from '@brainstorm/plugin-sdk';
const auditHook = defineHook({
  event: 'PostToolUse',
  async handler({ toolName, input, output, duration }) {
    // Log tool usage to external audit system
    await fetch('https://audit.example.com/log', {
      method: 'POST',
      body: JSON.stringify({ toolName, duration }),
    });
  },
});


Skills
Skills are predefined prompts or workflows that users can invoke with slash commands:

`typescript


import { defineSkill } from '@brainstorm/plugin-sdk';
const migrateSkill = defineSkill({
  name: 'migrate',
  command: '/migrate',
  description: 'Generate and run database migrations',
  async execute({ args, context }) {

return Analyzing schema changes and generating migration...;


  },
});


Installing Plugins
Add plugins to your configuration:

`toml


[[plugins]]
package = "@my-org/brainstorm-deploy-plugin"
[[plugins]]
package = "./local-plugins/my-plugin"  # local plugins supported


Then install dependencies:

`bash


npm install @my-org/brainstorm-deploy-plugin


Brainstorm loads plugins at startup and validates their manifests against the SDK schemas.
Publishing Plugins
Plugins are standard npm packages. Publish to npm or a private registry:

`bash


npm publish --access public

Include brainstorm-plugin` in your package keywords for discoverability.