Extension Tutorial

This tutorial walks through building a small external SwarmClaw extension and enabling it from the Extensions surface.

What You Build

A small extension that:

• adds one custom tool
• exposes one settings field
• demonstrates external extension install/update behavior

File Location

Create:

// data/extensions/release-guard.js
module.exports = {
  name: "release-guard",
  version: "1.0.0",
  description: "Adds a guarded release checklist tool.",
  tools: [
    {
      name: "release_guard",
      description: "Return a compact release checklist.",
      parameters: {
        type: "object",
        properties: {
          target: { type: "string" }
        },
        required: ["target"]
      },
      async execute(args) {
        return {
          ok: true,
          target: args.target,
          checklist: [
            "Run focused tests",
            "Confirm the release target",
            "Review rollback steps"
          ]
        }
      }
    }
  ],
  ui: {
    settingsFields: [
      { key: "defaultEnvironment", label: "Default Environment", type: "text" }
    ]
  }
}

Enable It

1. Open Extensions
2. Find release-guard
3. Enable it
4. Save any extension settings

Extension APIs

• GET /api/extensions
• POST /api/extensions
• DELETE /api/extensions
• GET /api/extensions/settings?pluginId=<id>
• PUT /api/extensions/settings?pluginId=<id>

The settings route still uses the pluginId query parameter internally because the external extension runtime is built on the existing extension/plugin file format.

Next Step

Use Extensions for the external extension model and Tools for built-in capability families.