Genesis plugins

A plugin adds new tools to Genesis. They appear on Home (with an automatic form), in the Assistant, in the CLI (genesis run ext.<plugin>.<tool>) and in jobs with a progress bar and a cancel button.

Technically a plugin is an MCP server over stdio packaged with a manifest. Genesis's SDKs implement the protocol in a single file with no dependencies, so your code only declares tools.

#Create one in a minute

genesis plugin new "My effects"                  # JavaScript / TypeScript (Node 18+)

genesis plugin new "My effects" --lang python    # Python 3.8+

Also from Settings → Plugins → Create plugin. It creates a folder with the manifest, the SDK and an example tool. Edit it and install it:

genesis plugin install ./my-effects

genesis run ext.my-effects.greet name=Ana

Reinstalling the same folder updates the plugin.

#Manifest: genesis-plugin.json

{
  "id": "my-effects",
  "name": "My effects",
  "version": "1.0.0",
  "description": "What it does, in one sentence.",
  "author": "Your name",
  "homepage": "https://…",
  "server": {
    "command": "node",
    "args": ["{plugin_dir}/index.mjs"],
    "env": { "MY_VARIABLE": "value" }
  }
}

#JavaScript / TypeScript SDK

genesis-plugin.mjs (+ genesis-plugin.d.ts with the types):

import { definePlugin } from "./genesis-plugin.mjs";

definePlugin({
  name: "my-effects",
  version: "1.0.0",
  tools: [
    {
      name: "reverse",
      title: "Reverse text",
      description: "Reverses a text.",
      input: {
        type: "object",
        properties: { text: { type: "string", format: "multiline" } },
        required: ["text"],
      },
      async run({ text }, { progress, signal }) {
        progress(0.5, "Reversing…");
        if (signal.aborted) throw new Error("cancelled");
        return { result: [...text].reverse().join("") };
      },
    },
  ],
});

#Python SDK

genesis_plugin.py:

from genesis_plugin import Plugin

plugin = Plugin("my-effects", "1.0.0")

@plugin.tool(
    description="Reverses a text.",
    input={"type": "object", "properties": {"text": {"type": "string"}}, "required": ["text"]},
)
def reverse(args, ctx):
    ctx.progress(0.5, "Reversing…")
    if ctx.cancelled:
        raise RuntimeError("cancelled")
    return {"result": args["text"][::-1]}

plugin.run()

Each call runs in its own thread, so a slow tool doesn't block the others.

#Inputs and results

• input is a JSON Schema. Genesis draws the form from it: enum creates a dropdown, boolean a checkbox, number/integer a numeric field and an array of paths a multiple file picker.
• Hints for strings: "format": "path" adds a button to pick a file, "save-path" one to choose where to save, and "multiline" a text area.
• Return an object (a structured result, which the Assistant and other tools can use), a string or nothing. Throwing an error shows it as a tool failure.
• To work with files, receive and return paths: Genesis opens the results in its editors and the gallery.
• progress(fraction 0..1, message) updates the job's bar; when the user cancels, signal (JS) or ctx.cancelled (Python) tells you.

#Distribute

Zip the folder (with the manifest at the root or inside a single folder) and share it. It's installed from Settings → Plugins → Install .zip or with genesis plugin install my-effects.zip. If your plugin needs dependencies (node_modules, Python packages), include them in the zip or vendor them: Genesis doesn't run package installers.

Plugins are stored in <data>/plugins/<id>; genesis plugin list, enable, disable and remove manage them.

#Examples

• examples/plugins/texto — JavaScript: text statistics and safe file names.
• examples/plugins/checksum — Python: SHA-256/MD5 file fingerprints with progress and cancellation.