Plugins

Add commands and agent tools to the desktop app and the CLI.

Plugins extend Peridot with slash commands and agent tools. The same plugin works in the desktop app and in the CLI.

• A command is something you type: /hello, /count-lines src/index.ts.
• An agent tool is something the model can call on its own while working, with the same approval rules as built-in tools.

Installing#

Desktop: click Plugins in the sidebar, browse the approved plugins and install one with a click.

CLI:

/plugin search lines
/plugin install line-counter
/plugin installed
/plugin uninstall line-counter

Plugins are installed on your computer in ~/.config/peridot/plugins, a folder shared by the desktop app and the CLI. Their commands then show up when you type /, and their tools are offered to the agent.

Review and safety#

Every plugin listed on tryperidot.io is reviewed before it is approved, and an install always gets the exact version that was approved, not whatever is on the author's repository today. When an author publishes a new version, it has to be reviewed again.

In the desktop app plugins run sandboxed: they can read only their own folder and the open project, and write only inside the project. Every tool a plugin adds declares whether it edits files or runs commands, so you approve it like any other.

Building a plugin#

A plugin is a TypeScript project in a public GitHub repository with a small manifest. A minimal one defines a command and a tool:

import { definePlugin } from "@peridot/plugin";

export default definePlugin({
  name: "hello",
  version: "1.0.0",
  description: "Says hello and counts lines in a file",

  // A slash command: /hello
  commands: {
    hello: {
      desc: "Say hello",
      usage: "[name]",
      run: async (args, ctx) => {
        ctx.print("Hello, " + (args[0] ?? ctx.user?.name ?? "world") + "!");
      },
    },
  },

  // A tool the agent can call. approval: null | "edit" | "command"
  tools: {
    count_lines: {
      description: "Count the lines in a file in the workspace",
      input: {
        type: "object",
        properties: { path: { type: "string", description: "File path" } },
        required: ["path"],
      },
      approval: null,
      run: async ({ path }: { path: string }, ctx) => {
        const text = ctx.workspace.readFile(path);
        return { ok: true, output: String(text.split("\n").length) };
      },
    },
  },
});

The agent sees the tool as hello__count_lines: the plugin name, two underscores, the tool name.

The full guide, with the manifest, the API and the review checklist, is in Writing a plugin. When you are ready, apply your plugin to get it reviewed and listed.

← Peridot CLI HTTP API →