Core plugin infrastructure for building BB (Beyond Better) AI assistant plugins. This package provides the base classes, interfaces, types, and plugin structure needed to create plugins containing tools and datasources that can be used with the BB AI assistant.
Note: This package may be renamed to @beyondbetter/plugins in the future.
- Plugin Structure: Structured
.bbpluginformat with manifest support - Multi-Component Support: Package multiple tools and datasources together
- Base Tool Class: Standardized LLMTool base class with consistent interfaces
- Dual Formatting: Browser (JSX/Preact) and console (ANSI) output formatting
- Type Safety: Comprehensive TypeScript type definitions
- Project & Conversation: Standardized interfaces for file and conversation management
- Input Validation: Built-in JSON Schema validation
- Testing Utilities: Extensive testing helpers and utilities
- Metadata Support: Plugin and tool metadata with examples
- Version Management: Semantic versioning with BB compatibility checks
- Distribution Ready: Double-click installation support (.bbplugin files)
Note: Standalone .tool directories are deprecated but still supported for backward compatibility.
# Using JSR
jsr add @beyondbetter/tools
# Using Deno
import { LLMTool } from "jsr:@beyondbetter/tools";- Create plugin package:
my-plugin.bbplugin/
├── manifest.json # Plugin metadata (required)
└── my-tool.tool/ # Tool directory
├── tool.ts # Main implementation
├── info.json # Tool metadata
├── formatter.browser.tsx # Browser formatting
├── formatter.console.ts # Console formatting
└── tool.test.ts # Tests
- Create plugin manifest (manifest.json):
{
"name": "my-plugin",
"version": "1.0.0",
"author": "Your Name",
"description": "Description of your plugin",
"license": "MIT",
"tools": ["my-tool.tool"],
"datasources": [],
"bbVersion": ">=0.9.0"
}- Define tool metadata (my-tool.tool/info.json):
{
"name": "my_tool",
"description": "Description of my tool",
"version": "1.0.0",
"author": "BB Team",
"license": "MIT",
"examples": [
{
"description": "Example usage",
"input": {
"param1": "value1"
}
}
]
}- Implement the tool (my-tool.tool/tool.ts):
import LLMTool, {
type IConversationInteraction,
type IProjectEditor,
type LLMToolRunResult,
type LLMAnswerToolUse
} from "@beyondbetter/tools";
class MyTool extends LLMTool {
constructor() {
super(
"my-tool",
"Description of my tool",
{}, // Tool config
{
mutates: false,
async: true,
requiresNetwork: false
}
);
}
get inputSchema() {
return {
type: "object",
properties: {
param1: { type: "string" }
},
required: ["param1"]
};
}
async runTool(
interaction: IConversationInteraction,
toolUse: LLMAnswerToolUse,
projectEditor: IProjectEditor
): Promise<LLMToolRunResult> {
const { param1 } = toolUse.toolInput;
return {
toolResults: \`Processed: \${param1}\`,
toolResponse: "Tool executed successfully",
bbResponse: { data: param1 }
};
}
formatLogEntryToolUse(toolInput, format) {
return format === "console"
? formatLogEntryToolUseConsole(toolInput)
: formatLogEntryToolUseBrowser(toolInput);
}
formatLogEntryToolResult(resultContent, format) {
return format === "console"
? formatLogEntryToolResultConsole(resultContent)
: formatLogEntryToolResultBrowser(resultContent);
}
}- Implement browser formatting (my-tool.tool/formatter.browser.tsx):
/** @jsxImportSource preact */
import LLMTool, {
type LLMToolInputSchema,
type LLMToolLogEntryFormattedResult,
} from '@beyondbetter/tools';
export function formatLogEntryToolUse(
toolInput: LLMToolInputSchema,
): LLMToolLogEntryFormattedResult {
return {
title: LLMTool.TOOL_TAGS_BROWSER.content.title('Tool Use', 'My Tool'),
subtitle: LLMTool.TOOL_TAGS_BROWSER.content.subtitle('Processing...'),
content: LLMTool.TOOL_TAGS_BROWSER.base.container(
<>
{LLMTool.TOOL_TAGS_BROWSER.base.label('Parameters')}
{LLMTool.TOOL_TAGS_BROWSER.base.list([
<>
{LLMTool.TOOL_TAGS_BROWSER.base.label('Value:')}{' '}
{LLMTool.TOOL_TAGS_BROWSER.content.text(toolInput.param1)}
</>,
])}
</>,
),
preview: 'Processing input...',
};
}- Implement console formatting (my-tool.tool/formatter.console.ts):
import { stripIndents } from 'common-tags';
import LLMTool, {
type LLMToolInputSchema,
type LLMToolLogEntryFormattedResult,
} from '@beyondbetter/tools';
export function formatLogEntryToolUse(
toolInput: LLMToolInputSchema,
): LLMToolLogEntryFormattedResult {
return {
title: LLMTool.TOOL_STYLES_CONSOLE.content.title('Tool Use', 'My Tool'),
subtitle: LLMTool.TOOL_STYLES_CONSOLE.content.subtitle('Processing...'),
content: stripIndents`
${LLMTool.TOOL_STYLES_CONSOLE.base.label('Parameters')}
${
LLMTool.TOOL_STYLES_CONSOLE.base.listItem(
stripIndents`
${LLMTool.TOOL_STYLES_CONSOLE.base.label('Value:')}
${LLMTool.TOOL_STYLES_CONSOLE.content.text(toolInput.param1)}`,
)
}`,
preview: 'Processing input...',
};
}- Install and use the plugin:
# Copy plugin to BB plugins directory
cp -r my-plugin.bbplugin ~/.config/bb/plugins/
# Or double-click the .bbplugin directory (macOS/Windows)
# BB will show installation dialog
# Restart BB API to load the plugin- Use the tool:
const tool = new MyTool();
const result = await tool.runTool(
conversationInteraction,
{
id: 'tool-use-1',
name: 'my-tool',
toolInput: {
param1: 'test input',
},
},
projectEditor,
);- Creating Plugins - Detailed guide for creating new plugins
- Testing Guide - Testing requirements and guidelines
- Plugin Framework Reference - Comprehensive framework documentation
- Plugin Manifest Schema - JSON schema for manifest.json
- Guidelines - Framework development guidelines
Base class for all tools:
- Input validation using JSON Schema
- Standardized execution flow
- Consistent formatting for browser and console
- Resource management
- Tool metadata support
Project management interface:
- File system access
- Change tracking
- Project configuration
- Resource management
Conversation management interface:
- File handling
- Tool usage tracking
- Token management
- Message formatting
- Fork the repository
- Create your feature branch
- Follow the Creating Plugins guide
- Follow the Guidelines for framework development
- Ensure tests pass using `deno test`
- Submit a pull request
# Run all tests
deno test
# Run with coverage
deno test --coverageSee Testing Guide for detailed testing requirements.
MIT License - see LICENSE file for details.
- BB (Beyond Better) - AI assistant using this tool framework
- @beyondbetter/types - Shared types for BB projects