Building a plugin for Vyrgent

The idea

What a plugin is

One .js file that exports a tool. When the file is valid, Vyrgent registers it automatically and the assistant can call it whenever a request matches what the tool does. Plugins live in your ~/.vyrgent/plugins/ folder and hot-reload — save the file and it updates live, no restart.

Under the hood, a plugin is a CommonJS module: it sets module.exports to an object with four required fields.

The contract

What every plugin must export

Vyrgent validates each file on load. If any of the four required fields is missing, the plugin is rejected with a clear error and won't appear as a tool.

Copy this

The template

A complete, working plugin. Save it as e.g. currency_convert.js, change the four fields to fit your tool, and load it.

// A Vyrgent plugin is a CommonJS module: set module.exports to an object.
module.exports = {
  // 1) name — unique, snake_case, no spaces. This is the tool's ID.
  name: "currency_convert",

  // 2) description — the assistant reads THIS to decide when to call the
  //    tool. Say plainly what it does and when to use it.
  description: "Convert an amount from one currency to another (e.g. 100 USD to EUR). Use when the user asks to convert money between currencies.",

  // Optional metadata.
  version: "1.0.0",
  configKeys: [],        // e.g. ["exchangeApiKey"] to read a saved key
  timeout: 30000,        // 30s (optional)

  // 3) input_schema — JSON Schema for the arguments. Give every property a
  //    clear "description"; the assistant fills them from the user's request.
  input_schema: {
    type: "object",
    properties: {
      amount: { type: "number", description: "How much to convert." },
      from:   { type: "string", description: "Source currency code, e.g. USD." },
      to:     { type: "string", description: "Target currency code, e.g. EUR." },
    },
    required: ["amount", "from", "to"],
  },

  // 4) handler — runs when the tool is called. Return a STRING; the text
  //    is what the assistant sees and relays. Throw an Error to fail.
  async handler({ input, config, services }) {
    const { amount, from, to } = input;

    // Validate inputs and return a clear message on bad data.
    if (!amount || !from || !to) return "Please provide amount, from, and to.";

    // Do the work. Fetch is available; so are Node built-ins.
    const res = await fetch(`https://api.exchangerate.host/convert?from=${from}&to=${to}&amount=${amount}`);
    if (!res.ok) throw new Error(`Exchange API error (HTTP ${res.status}).`);
    const data = await res.json();

    // Return a concise, human-readable string.
    return `${amount} ${from} = ${data.result.toFixed(2)} ${to}`;
  },
};

Inside the handler

What your handler receives

Every handler is called with one object: { input, config, services }.

Load it

Installing your plugin

1. Open Vyrgent → Settings → Plugins.
2. Click Install from file and choose your .js file. (Or copy it straight into ~/.vyrgent/plugins/.)
3. It loads instantly and hot-reloads on every save — no restart needed.
4. Ask the assistant to do the thing your plugin does. It routes to your tool automatically when the request matches the name or description.

Do it well

Best practices

• Write the description for the assistant. It's how the tool gets chosen. Name the action and the trigger ("Use when the user asks to…"). Vague descriptions never get called.
• Describe every input property. The assistant fills arguments from those descriptions — the clearer they are, the better it fills them.
• Fail loudly, don't retry. If something breaks, throw new Error(...) with the real reason. Don't silently return fake success.
• Keep secrets in configKeys. Read API keys from config, never paste them into the file.
• Never run synchronous subprocesses. Avoid execSync/spawnSync for anything slow — a blocking child process freezes the whole app. Use the async forms with await.
• Return concise strings. The handler's return text goes to the assistant — a short, clear result beats a giant dump.

If it won't load

Common validation errors

Vyrgent will refuse a file and tell you exactly what's wrong. The four messages map straight to the required fields: