Building Plugins

Step-by-step guide to creating a Beige plugin

Quick Start: Tool-Only Plugin

The simplest plugin wraps a CLI tool or API.

Step 1: Create the package

plugins/my-tool/
├── plugin.json
├── index.ts
├── README.md
└── SKILL.md

Step 2: Write the manifest

{
  "name": "my-tool",
  "description": "Does something useful",
  "commands": ["run <input>  — Process input"],
  "provides": { "tools": ["my-tool"] }
}

Step 3: Implement the plugin

import type { PluginContext, PluginRegistrar, PluginInstance } from "@matthias-hausberger/beige";

export function createPlugin(
  config: Record<string, unknown>,
  ctx: PluginContext
): PluginInstance {
  return {
    register(reg: PluginRegistrar) {
      reg.tool({
        name: "my-tool",
        description: "Does something useful",
        commands: ["run <input>  — Process input"],
        handler: async (args) => {
          const [command, ...rest] = args;
          if (command === "run") {
            return { output: `Processed: ${rest.join(" ")}`, exitCode: 0 };
          }
          return { output: `Unknown command: ${command}`, exitCode: 1 };
        },
      });
    },
  };
}

Step 4: Write documentation

SKILL.md (for agents):

# my-tool — Usage Guide

## Calling Convention
```sh
my-tool <command> [args...]

Examples

my-tool run hello world

**README.md** (for users):
```markdown
# my-tool

A Beige plugin that does something useful.

## Configuration
No configuration needed.

Step 5: Register in config

{
  plugins: {
    "my-tool": {
      path: "./plugins/my-tool",
    },
  },
  agents: {
    assistant: {
      tools: ["my-tool"],
    },
  },
}

Step 6: Restart the gateway

beige gateway restart

---

Multi-Tool Plugin

If your plugin provides multiple tools, use dot notation:

register(reg) {
  reg.tool({
    name: "mycloud.deploy",
    description: "Deploy an application",
    handler: async (args) => { ... },
  });
  reg.tool({
    name: "mycloud.logs",
    description: "View application logs",
    handler: async (args) => { ... },
  });
}

Agent config:

agents: {
  assistant: {
    tools: ["mycloud.deploy", "mycloud.logs"],
  },
}

---

Channel Plugin

A plugin that provides a messaging channel:

export function createPlugin(config, ctx) {
  return {
    register(reg) {
      reg.channel({
        sendMessage: async (chatId, threadId, text) => { ... },
        supportsMessaging: () => true,
      });

      // Optionally register tools too
      reg.tool({
        name: "mychannel.send",
        description: "Send a proactive message",
        handler: async (args) => { ... },
      });
    },

    async start() {
      // Start receiving messages (polling, webhook, etc.)
    },

    async stop() {
      // Clean up
    },
  };
}

---

Plugin with Hooks

A plugin that intercepts messages:

export function createPlugin(config, ctx) {
  return {
    register(reg) {
      reg.hook("prePrompt", async (event) => {
        // Log every message
        console.log(`Message from ${event.channel}: ${event.message.slice(0, 50)}`);
        return { message: event.message };
      });

      reg.hook("postResponse", async (event) => {
        // Strip sensitive data
        const cleaned = event.response.replace(/secret/gi, "***");
        return { response: cleaned };
      });
    },
  };
}

---

Cross-Plugin Interaction

Plugins can invoke tools from other plugins via ctx.invokeTool():

// A scheduler plugin that calls git from another plugin
async function runDailySync(ctx) {
  const result = await ctx.invokeTool("git", ["pull", "origin", "main"]);
  if (result.exitCode !== 0) {
    console.error("Daily sync failed:", result.output);
  }
}

---

Distributing Plugins

As an npm package

npm publish
# Users install with:
beige plugins install npm:@your-scope/your-plugin

As a GitHub repo

# Users install with:
beige plugins install github:your-org/your-plugin

Package with multiple plugins

Put multiple plugins in subdirectories:

my-toolkit/
├── plugins/
│   ├── git/
│   │   ├── plugin.json
│   │   └── index.ts
│   ├── github/
│   │   ├── plugin.json
│   │   └── index.ts
│   └── slack/
│       ├── plugin.json
│       └── index.ts
└── package.json

All plugins are discovered and installed automatically.

---

Migration from v1 Tools

If you have existing tools using the old tool.json + createHandler() format:

// Old format (v1)
export function createHandler(config, ctx) {
  return async (args, _, sessionContext) => {
    return { output: "result", exitCode: 0 };
  };
}

// New format (v2)
export function createPlugin(config, ctx) {
  return {
    register(reg) {
      reg.tool({
        name: "my-tool",
        description: "...",
        handler: async (args, _, sessionContext) => {
          return { output: "result", exitCode: 0 };
        },
      });
    },
  };
}

Rename tool.json to plugin.json and update its structure to match the plugin manifest format (see above).